minimize path-nesting

[geemus]

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]

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. 👍

[geemus]

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]

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

[geemus]

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