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

[Patrick Creech]

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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 488 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20171117/0a6c68ef/attachment.sig>