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

[Jeff Ortel]

On 11/27/2017 12:19 PM, Jeff Ortel wrote:
> 
> 
> On 11/17/2017 08:55 AM, Patrick Creech 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
> 
> The order/items is a good example of aggregation (or composition) and I agree it makes a strong case for
> nesting.  In pulp, a repository is easily thought of as a collection or aggregation of content.
> 
>>
>> 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.
> 
> I don't think the aggregation relationship exists between repository and importer/publisher.  There is a
> strong association between repository and importer/publisher which /could/ even be characterized as
> "ownership".  However, I don't think there is an aggregation (or composition) relationship.  The same for
> publisher & publication.  A publication is associated to its creating publisher but the publisher isn't an
> aggregation of publications.  The relationship mainly provides linkage to the repository.

This is not an argument to flatten the URLs but meant to clarify the relationships.

> 
>>
>> --------------------------------------------------------------
>> 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.
> 
> Agreed.
> 
> Also, I don't think nesting impacts URL readability.
> 
>>     
>>     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
>>
> 

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 847 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20171127/6ee320f1/attachment.sig>