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. > > -------------------------------------------------------------- > 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@redhat.com > https://www.redhat.com/mailman/listinfo/pulp-dev >
signature.asc
Description: OpenPGP digital signature
_______________________________________________ Pulp-dev mailing list Pulp-dev@redhat.com https://www.redhat.com/mailman/listinfo/pulp-dev