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

[Austin Macdonald]

<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.

Nested PK URL for a Publication (artist's rendering):

http://pulp3.dev:8000/api/v3/repositories/a6287821-5d13-4a59-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-4a59-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
   4. More flexible for forward compatibility.
   5. 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.**

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?
   - 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.
   - 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.


[0]:
https://github.com/pulp/pulp/blob/3.0-dev/pulpcore/pulpcore/app/urls.py#L15-L106
[1]:
https://github.com/pulp/pulp/blob/3.0-dev/pulpcore/pulpcore/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/pulpcore/app/viewsets/repository.py#L119-L123
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20171116/36b36a61/attachment.htm>