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

[Bihan Zhang]

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