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

Tue Nov 21 13:56:53 UTC 2017

Would users ever want to search across all importers or publishers? For
example, maybe a user wants to see what importers match a particular feed
url or don’t have proxy settings set. How would we enable that in a nested
API?

David

On Fri, Nov 17, 2017 at 10:19 AM, Tom McKay <thomasmckay at redhat.com> wrote:

> I don't know how this works, but in github I see "Latest commit 898584a 3
> days ago" and clicking through gives me the full
> "898584a7d241618b2d9206d21eaf2fbd0a75ecd7". As a user, I like the the
> convenience of the shorter id for use in command line interactions and
> displayed in UI.
>
> On Fri, Nov 17, 2017 at 10:08 AM, Bihan Zhang <bizhang at redhat.com> wrote:
>
>> Personally, I believe that a hierarchical structure makes sense in our
>> API design.
>>
>> Importers/Publishers are unique to a repository, they cannot switch their
>> repository parent, and they cannot exist without a repository. When a
>> repository is deleted, its related importers and publisher are deleted as
>> well, as they are meaningless without the context of the parent Repository.
>>
>> I think a lot of URL design issues can be resolved by having better
>> filters like:
>>     GET /api/v1/people/?item_name=Concentrated%20Sprayflesh
>> Not necessarily by allowing users to work with items directly (you might
>> want that for other reasons, but for not for getting all the user with
>> sprayflesh in their inventory, because I don't think exposing the user-item
>> join table in /items/1/ makes a lot of sense.)
>>
>> I think as far as pulp3 goes, as long as we provide good filter support
>> we can meet all of a user's needs. I did find a library that support
>> relationship filters through drf: https://github.com/philipn/dja
>> ngo-rest-framework-filters that might be viable to pull in (Open Source
>> FTW!)
>>
>> Our initial reasoning for switching from naturals keys in URLs to pk
>> instead of making natural keys immutable was that URLs do not need to be
>> human friendly and pretty. Perhaps we should revisit that decision if human
>> readable urls are our goal.
>>
>>
>> On Fri, Nov 17, 2017 at 9:55 AM, Patrick Creech <pcreech at redhat.com>
>> wrote:
>>
>>> One of the things I like to think about in these types of situations is,
>>> "what is good rest api
>>> design".  Nesting resources under other resources is a necessary part of
>>> good api design, and has
>>> its place.  To borrow some terms from domain driven development:
>>>
>>> Collections of objects are called aggregates.  Think 'an order and its
>>> line items'.  Line items make
>>> no sense without having the order context, so they are an aggregate that
>>> is accessed under an
>>> Order.  This is called the aggregate root.  The rest api design for such
>>> an object, using order as
>>> the aggregate root, would look like:
>>>
>>> '/orders/' -- all orders
>>> '/orders/{order_key}/' -- a specific order with key.
>>> '/orders/{order_key}/items/' -- All of the order's items.
>>> '/orders/{order_key}/items/{item_key}/' -- a specific line item of the
>>> order
>>>
>>> When it comes to order items themselves, it isn't helpful to start with
>>> them as their own aggregate
>>> root in one large collection:
>>>
>>> '/items/'   -- all order items in the system
>>>
>>> Because you lose the order context. Based on api design, this endpoint
>>> will need to respond with all
>>> order items across all orders and resort to parameter filtering to
>>> provide the context you need.
>>>
>>> A quote borrowed from Martin Fowler [0]
>>>
>>> "An aggregate will have one of its component objects be the aggregate
>>> root. Any references from
>>> outside the aggregate should only go to the aggregate root. The root can
>>> thus ensure the integrity
>>> of the aggregate as a whole."
>>>
>>> Publishers, importers, and publications are all aggregates that don't
>>> make much sense outside of
>>> their aggregate root of Repository.  They are dependent on the
>>> Repository context, and from a domain
>>> view, should be accessed starting with their specific Repository
>>> endpoint.
>>>
>>> --------------------------------------------------------------
>>> Specific items rebuttals:
>>>
>>>     Yes, using the primary key uuid's as the immutable key adds some
>>> human readable challenges to
>>> the API.  That sounds more like a point to discuss in the human readable
>>> vs. not human readable
>>> immutable key debate.
>>>
>>>     One of the challenges in software engineering is ensuring the tools
>>> you are using don't limit
>>> your choices.  DRF limited the choices for pulp's rest API design, and
>>> drf-nested-routers was
>>> introduced to help remove that limit.  If working around these
>>> limitations is complex, take
>>> advantage of open source here and help improve the upstream dependencies
>>> for your workflow.
>>>
>>>     As far as making things simpler for plugin writers, perhaps there
>>> are ways you can simplify it
>>> for them by providing some encapsulation in pulp's core instead.
>>> Abstract away the nasty bits
>>> behind the scenes, and provide them with a simpler interface to do what
>>> they need.
>>>
>>>     With respect to the invested time already in making this work, I
>>> agree with jeremy that it
>>> should be considered part of the sunken cost fallacy.  What does need to
>>> be evaluated though is how
>>> much time re-architecting at this point will cost you (discussion,
>>> planning, and development) vs the
>>> amount of time it will save, and weigh that against any planned
>>> milestones for pulp to see if it
>>> will push them out as well.
>>>
>>>     I'm also in agreement that it is moot if pulp3 has a different api
>>> structure than pulp2.  Major
>>> version boundaries are the perfect time for evaluating and moving such
>>> things around.
>>>
>>> [0] https://martinfowler.com/bliki/DDD_Aggregate.html
>>> _______________________________________________
>>> Pulp-dev mailing list
>>> Pulp-dev at redhat.com
>>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>>
>>>
>>
>> _______________________________________________
>> Pulp-dev mailing list
>> Pulp-dev at redhat.com
>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>
>>
>
> _______________________________________________
> 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/20171121/5a9d3abb/attachment.htm>