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

Tom McKay thomasmckay at redhat.com
Fri Nov 17 15:19:12 UTC 2017

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/
> django-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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20171117/83f32917/attachment.htm>

More information about the Pulp-dev mailing list