[Pulp-dev] Plan to handle ids and hrefs

[David Davis]

After some discussions, we’ve decided to change course and not support IDs
in our API. Instead, we’ll be relying on hrefs to reference objects.

Below is the new plan. Feedback as always is welcome. Please respond by the
end of next week (August 31, 2018).

# Summary

We will use hrefs to refer to resources. This is how the code currently
works today.

# Response Data

Use relative URIs. e.g. https://example.com/pulp/api/v3/repositories/file/1/
-> /pulp/api/v3/repositories/file/1/

# Submitting Data (both work)

Preferred:

POST 'https://example.com/pulp/api/v3/remote/file/4/sync/'
repository='/pulp/api/v3/repositories/file/1/‘

This also works too:

POST 'https://example.com/pulp/api/v3/remote/file/4/sync/' repository='
https://example.com/pulp/api/v3/repositories/file/1/'

# Binding example

https://github.com/dkliban/pulp3-python-bindings/blob/href-as-identifier/swagger_client/api/content_api.py#L234

# Reasons

(a) it's a simpler user experience. They only store 1 string, not json
hashes including the type and possible multiple pks
(b) resources like repositoryVersion don’t have to be un-nested
(c) simpler, don't have to support both ID and href
(d) it already works

# Next Steps

* enable the bindings by merging https://github.com/pulp/pulp/pull/3561
* Need to switch full hrefs currently returned for relative href's to be
returned. i.e. https://example.com/pulp/api/v3/repositories/file/1/   ->
/pulp/api/v3/repositories/file/1/
  - Issue: https://pulp.plan.io/issues/3850

David


On Wed, Aug 8, 2018 at 12:22 PM David Davis <daviddavis at redhat.com> wrote:

> Yea, the names here are in terms of the names we use today and are subject
> to the outcome of the field naming thread.
>
> David
>
>
> On Wed, Aug 8, 2018 at 12:17 PM Daniel Alley <dalley at redhat.com> wrote:
>
>>  As per the other discussion thread, I assume the names will actually be
>> _id, _type, _href?
>>
>> Errata have both "id" and "type" fields, so if we're going to attempt to
>> keep the Pulp metadata field names out of the way of Content field names,
>> we need to do it for all of them.
>>
>> On Wed, Aug 8, 2018 at 12:02 PM, David Davis <daviddavis at redhat.com>
>> wrote:
>>
>>> After recent meetings with stakeholders, we've arrived at a solution on
>>> how to handle ids and hrefs in the Pulp 3 API. The plan is to stop
>>> accepting hrefs for fields to instead rely solely on IDs. Hrefs will still
>>> be displayed in the API as a convenience to users but will not be accepted
>>> for fields in POST/PUT requests.
>>>
>>> In order to support polymorphic fields, we'll also be adding a 'type'
>>> field that will be returned for all objects that will contain the package
>>> name and resource name (e.g. pulp_file.FileContent). This will allow these
>>> objects to be posted to polymorphic fields like
>>> add_content_units/remove_content_units (see below).
>>>
>>> Lastly, we also propose un-nesting the repository versions endpont and
>>> making it a top-level resources. Filtering of repository versions
>>> associated with a specific repo will be handled by repo filters, e.g.
>>> /pulp/api/v3/repository_versions/?repository=3
>>>
>>>
>>> RETURNING DATA
>>>
>>> Return for all objects:
>>> - id
>>> - _href
>>> - type
>>>
>>> e.g. {'id': 4, 'type': 'pulp_file.FileContent', '_href': '
>>> http://localhost:8000/pulp/api/v3/content/file/files/4/'}
>>>
>>> This includes polymorphic fields (e.g. created_resource on TaskStatus)
>>>
>>>
>>> POSTING DATA
>>>
>>> Submitting data in general will use id only (no hrefs). For example:
>>>
>>> http http://localhost:8000/pulp/api/v3/remotes/file/3/sync repository=3
>>>
>>> Submitting polymorphic fields can be handled in the following way:
>>>
>>> add_content_units=[
>>>     {'id': 4, 'type': 'pulp_file.FileContent', '_href': '
>>> http://localhost:8000/pulp/api/v3/content/file/files/4/'},
>>>     {'id': 4, 'type': 'pulp_python.PythonContent', '_href': '
>>> http://localhost:8000/pulp/api/v3/content/python/p/4/'}
>>> ]
>>>
>>> Note: the only fields that are inspected are id and type. the rest are
>>> ignored. This simply allows users to pass back the data they receive from
>>> the content endpoint.
>>>
>>>
>>> We're holding off on proceeding until August 15th to allow time for
>>> comment. Please respond with any concerns or feedback before then.
>>>
>>>
>>> _______________________________________________
>>> Pulp-dev mailing list
>>> Pulp-dev at redhat.com
>>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>>
>>>
>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20180824/ebf234d5/attachment.htm>