search

interagent / http-api-design

HTTP API design guide extracted from work on the Heroku Platform API
https://geemus.gitbooks.io/http-api-design/content/en/
Other
13.69k stars 1.07k forks source link

minimize path-nesting #49

Open geemus opened 10 years ago

geemus commented 10 years ago

Having things at the top level in most cases improves consistency and helps avoid (at least in some cases) n+1 issues. That said, nested things make since to provide a scope for returning lists in particular (and some things can not easily be de-nested because they do not have globally unique identifiers, but this should probably be avoided also). Anyway... There are some gotchas to this approach, but overall we have tried it a few times and have been finding it useful, so I'd like to expound upon the virtues and usage within the guide (and wanted to start by adding some notes here).

bjeanes commented 10 years ago

I think nesting for scoping can be nice, but the other actions (update, destroy, etc) on resources should probably be done at the root level with a unique identifier. :+1:

geemus commented 10 years ago

Yeah, that was my suspicion before and I think we have enough experience with it now to push toward it more concretely. It does mean more places where nested foreign keys need to be included, but I think that is not a bad thing. Thanks for the further validation!

muescha commented 10 years ago

then it would be nice to see how to do the scoping without nesting.

geemus commented 10 years ago

@muescha yeah, ultimately you would end up with some duplication. An example: given resource and subresource, you'd have these routes:

POST /subresources # create
GET /subresources/{identifier} # info
GET /subresources # list
GET /resource/{identifier}/subresources # list with scope
PATCH /subresources/{identifier} # update
DELETE /subresources/{identifier} # delete

So the scoped one is duplicated to appear with nesting (to scope) and without nesting for the global view. All of the actions that operate on individual things happen at the top level though (instead of also being nested). I think this is nice in that there is never a question of where to operate on a particular object (always at the top level). Hope that clarifies, I want to write this up better, but wanted to provide a bit more detail in the mean time.