[Pulp-dev] Proposal and feedback request: un-nest urls

Fri Nov 17 14:32:27 UTC 2017

On Thu, Nov 16, 2017 at 2:45 PM, Austin Macdonald <austin at redhat.com> wrote:

> <tldr>
>
> We recently decided to reference objects by their pks in the urls,
> primarily so they will be immutable. Problem: UUIDs are long, and not human
> friendly. Add nesting and urls get ugly.
>

I'd like to tweak that description slightly. I think we decided to
reference objects by an opaque and portable unique identifier, and it
happens that the UUIDs being used for the primary key were a good fit for
that. It's valuable to maintain a conceptual separation between the
database primary key and the public API unique identifier, and it's very
common for true REST APIs to use different values for each.

It's fine that we have one value doing double duty, but I would hesitate to
talk about a "primary key" in the domain of the REST API.

> Nested PK URL for a Publication (artist's rendering):
>  http://pulp3.dev:8000/api/v3/repositories/a6287821-5d13-4a5
> 9-8a34-a7ea98bcc40d/publishers/file/a6287821-5d13-4a59-8a34-
> a7ea98bcc40d/publications/a6287821-5d13-4a59-8a34-a7ea98bcc40d
>
> Flat URL for a publication:
>  http://pulp3.dev:8000/api/v3/publications/a6287821-5d13-4a5
> 9-8a34-a7ea98bcc40d
>
> Proposal:
> Move all nested ViewSets (Repositories, Importers, Publishers,
> Distributions, Publications) to top level endpoints. I'll write up as a
> task after some feedback/discussion.
>
> </tldr>
>
> Benefits:
>
>    1. Drop dependency on drf-nested-routers.
>    2. Drop custom code to integrate drf-nested-routers with
>    master/detail. (This is the most complex part of writing ViewSets and
>    Serializers.)
>    3. Simple URLs
>
> I'm not sure this has any practical benefit. I'd say that while the URLs
would be shorter, they would convey less information, and in particular
would contain less information about the identify of an object. They
clearly would still have enough to uniquely identify the object, but would
miss the fact that a publication is defined in part by the publisher that
created it, and the repository whose content set it was created from.

>
>    1.
>    2. More flexible for forward compatibility.
>
>
Can you elaborate on this?

>
>    1. Much easier for everyone if our use of drf more similar to their
>    docs.
>
> Cons:
>
>    1. Lost investment in nesting.
>    2. Different structure than Pulp 2.
>
> Code we can drop:
>
>    1. ViewSet registration and Router creation. [0]
>    2. Fields that reference a relationship to a nested object. [1][2]
>    3. Extra class attributes on ViewSets. [3]
>
> Complexity: Obviously, drf is designed to extend Django, and drf-nested is
> designed to extend drf, but that relationship only goes in one direction.
> In particular, the intersection of Master/Detail with nested urls adds a
> lot of complexity, and the REST API becomes pretty complex. This
> combination of factors can easily obscure problems. **This complexity is
> passed on to plugin writers.**
>

Can you elaborate on how the complexity is passed on? Is there a way for us
to make it easy on them?

>
> In need of thought and discussion:
>
>    - We agreed to allow plugin writers to create custom ViewSets. Does
>    this mean that their ViewSets must also be top level, or can they own a
>    namespace?
>
>
I'm not quite sure what you mean by this. But I would be careful to clearly
identify what part of the REST API is provided by a plugin, vs. which part
is covered by core's compatibility guarantee.

>
>    - Master/Detail objects are semi-nested. A publisher endpoint might
>    be: `v3/publishers/file/<PK>/`. Is this what we want?
>    - If "name" and other natural keys are no longer used in the URLs, we
>    could stop thinking of them as part of the object. Specifically, I imagine
>    that "name" could instead become a "tag". This opens up some interesting
>    workflow ideas, but this is a tangent.
>
> From a user perspective, the natural key will still be how they uniquely
identify these resources. It will likewise be important for us to continue
making uniqueness guarantees about them.

>
>    - Thinking forward, specifically to Versioned Repositories, separating
>    the object relationships from our URL structure allows us much more freedom
>    to make changes without being backwards incompatible. This is concerning
>    because repos are the root of all nesting.
>
> Do you have an example in mind of a change that would be
backward-compatible only when nesting is in use? All I can think of is a
case where a resource changed location within the path space, but I'm not
sure what that would happen.

>
> [0]: https://github.com/pulp/pulp/blob/3.0-dev/pulpcore/pulp
> core/app/urls.py#L15-L106
> [1]: https://github.com/pulp/pulp/blob/3.0-dev/pulpcore/pulp
> core/app/serializers/base.py#L310-L331
> [2]: https://github.com/pulp/pulp/blob/3.0-dev/pulpcore/pulpcore/
> app/serializers/repository.py#L50-L57
> [3]: https://github.com/pulp/pulp/blob/3.0-dev/pulpcore/pulp
> core/app/viewsets/repository.py#L119-L123
>
> _______________________________________________
> Pulp-dev mailing list
> Pulp-dev at redhat.com
> https://www.redhat.com/mailman/listinfo/pulp-dev
>
>

-- 

Michael Hrivnak

Principal Software Engineer, RHCE

Red Hat
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20171117/8d2207fb/attachment.htm>