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@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
