<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Thu, Nov 16, 2017 at 2:45 PM, Austin Macdonald <span dir="ltr"><<a href="mailto:austin@redhat.com" target="_blank">austin@redhat.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div><tldr></div><div><br></div>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. </div></blockquote><div><br></div><div>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.</div><div><br></div><div>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.</div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div><div></div><div>Nested PK URL for a Publication (artist's rendering):</div><div> <a href="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" target="_blank">http://pulp3.dev:8000/api/v3/<wbr>repositories/a6287821-5d13-4a5<wbr>9-8a34-a7ea98bcc40d/publishers<wbr>/file/a6287821-5d13-4a59-8a34-<wbr>a7ea98bcc40d/publications/<wbr>a6287821-5d13-4a59-8a34-<wbr>a7ea98bcc40d</a></div><div><br></div><div>Flat URL for a publication:</div><div> <a href="http://pulp3.dev:8000/api/v3/publications/a6287821-5d13-4a59-8a34-a7ea98bcc40d" target="_blank">http://pulp3.dev:8000/api/v3/<wbr>publications/a6287821-5d13-4a5<wbr>9-8a34-a7ea98bcc40d</a></div><div><br><div><div>Proposal:</div><div>Move all nested ViewSets (Repositories, Importers, Publishers, Distributions, Publications) to top level endpoints. I'll write up as a task after some feedback/discussion.</div></div></div><div><br></div><div></tldr></div><div><br></div><div>Benefits:</div><div><ol><li>Drop dependency on drf-nested-routers.</li><li>Drop custom code to integrate drf-nested-routers with master/detail. (This is the most complex part of writing ViewSets and Serializers.)</li><li>Simple URLs<br></li></ol></div></div></div></blockquote><div>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.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div><div><ol><li></li><li>More flexible for forward compatibility.<br></li></ol></div></div></div></blockquote><div><br></div><div>Can you elaborate on this?</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div><div><ol><li>Much easier for everyone if our use of drf more similar to their docs.</li></ol><div>Cons:</div></div><div><ol><li>Lost investment in nesting.</li><li>Different structure than Pulp 2.<br></li></ol></div><div>Code we can drop:<ol><li>ViewSet registration and Router creation. [0]</li><li>Fields that reference a relationship to a nested object. [1][2]</li><li>Extra class attributes on ViewSets. [3]</li></ol><div>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.**</div></div></div></div></blockquote><div><br></div><div>Can you elaborate on how the complexity is passed on? Is there a way for us to make it easy on them?</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div><div><div><br></div><div>In need of thought and discussion:</div><div><ul><li>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?</li></ul></div></div></div></div></blockquote><div><br></div><div>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.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div><div><div><ul><li>Master/Detail objects are semi-nested. A publisher endpoint might be: `v3/publishers/file/<PK>/`. Is this what we want?</li><li>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.</li></ul></div></div></div></div></blockquote><div>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.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div><div><div><ul><li>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.</li></ul></div></div></div></div></blockquote><div>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.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div><div><div><div><br></div></div><div>[0]: <a href="https://github.com/pulp/pulp/blob/3.0-dev/pulpcore/pulpcore/app/urls.py#L15-L106" target="_blank">https://github.com/pulp/p<wbr>ulp/blob/3.0-dev/pulpcore/pulp<wbr>core/app/urls.py#L15-L106</a></div></div><div>[1]: <a href="https://github.com/pulp/pulp/blob/3.0-dev/pulpcore/pulpcore/app/serializers/base.py#L310-L331" target="_blank">https://github.com/pulp/p<wbr>ulp/blob/3.0-dev/pulpcore/pulp<wbr>core/app/serializers/base.py#<wbr>L310-L331</a></div><div>[2]: <a href="https://github.com/pulp/pulp/blob/3.0-dev/pulpcore/pulpcore/app/serializers/repository.py#L50-L57" target="_blank">https://github.com/pulp/pulp/b<wbr>lob/3.0-dev/pulpcore/pulpcore/<wbr>app/serializers/repository.py#<wbr>L50-L57</a><br></div><div>[3]: <a href="https://github.com/pulp/pulp/blob/3.0-dev/pulpcore/pulpcore/app/viewsets/repository.py#L119-L123" target="_blank">https://github.com/pulp/p<wbr>ulp/blob/3.0-dev/pulpcore/pulp<wbr>core/app/viewsets/repository.<wbr>py#L119-L123</a><br></div></div></div>
<br>______________________________<wbr>_________________<br>
Pulp-dev mailing list<br>
<a href="mailto:Pulp-dev@redhat.com" target="_blank">Pulp-dev@redhat.com</a><br>
<a href="https://www.redhat.com/mailman/listinfo/pulp-dev" rel="noreferrer" target="_blank">https://www.redhat.com/mailman<wbr>/listinfo/pulp-dev</a><br>
<br></blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="m_5792714454681454542gmail_signature" data-smartmail="gmail_signature"><div dir="ltr"><p style="color:rgb(0,0,0);font-family:overpass-mono,monospace;font-size:10px;margin:0px!important;padding:0px!important"><span style="margin:0px!important;padding:0px!important">Michael</span> <span style="margin:0px!important;padding:0px!important">Hrivnak</span></p><p style="color:rgb(0,0,0);font-family:overpass-mono,monospace;font-size:10px;margin:0px!important;padding:0px!important"></p><span style="color:rgb(0,0,0);font-family:overpass-mono,monospace;font-size:10px;margin:0px!important;padding:0px!important"><span style="margin:0px!important;padding:0px!important">Principal Software Engineer</span><span style="margin:0px!important;padding:0px!important">, <span style="margin:0px!important;padding:0px!important">RHCE</span></span> </span><span style="color:rgb(0,0,0);font-family:overpass-mono,monospace;font-size:10px"></span><br style="color:rgb(0,0,0);font-family:overpass-mono,monospace;font-size:10px;margin:0px!important;padding:0px!important"><p style="color:rgb(0,0,0);font-family:overpass-mono,monospace;font-size:10px;margin:0px!important;padding:0px!important">Red Hat</p></div></div>
</div></div>