3 ms·

This is one issue I struggled with in my last API design. I generally like the /comments?post_id=232 format but in many cases it's not intuitive. Especially w

This is one issue I struggled with in my last API design. I generally like the /comments?post_id=232 format but in many cases it's not intuitive. Especially when the sub-resource (i.e. comments) is only ever referenced in with a parent resource (i.e. posts). This is a bit of a contrived example but with a structure like /comments?post_id=232, a developer might mistakenly assume comments are independent resources and not explicitly tied to posts when, in reality, there are can be no comments without posts. In this case, /posts/343/comments is much more intuitive. The way we ended up handling it was forcing ourselves to limit sub-resources to a maximum of 1 level deep. So /posts/343/comments was allowable but something like /posts/343/comments/23/author was not allowed.

friendzis 10y ago
In my view, arbitrary limits are also not too intuitive :) Problem with nesting is that very rarely your resource classes will make an acyclic graph. Even in your example '/posts/343/comments/23/author' resource class AUTHOR may be a child of either comment or the post itself. And if a user wants to view all posts by particular author? Intuitive use might as well be '/posts/343/comments/23/author/posts/123/comments' ad infinitum :) Such problems can be solved by providing an endpoint for each distinct resource class and making it search provider. In your example case 3 endpoints are needed: /post, /comment, /author, all accepting other two as search parameters, e.g. /author?comment=123456 or /author?comments|id=123456 (inspired by FHIR).
andreasklinger 10y ago
my reasoning: you end up w/ a lot of filters very quickly and related post id will be just one of them also linking it to another resource usually involved expecting defaults (default ordering, default display, pagination etc) if you stay "flat" this tends to be less of an issue when usecases become more complex

friendzis 10y ago

In my view, arbitrary limits are also not too intuitive :) Problem with nesting is that very rarely your resource classes will make an acyclic graph. Even in your example '/posts/343/comments/23/author' resource class AUTHOR may be a child of either comment or the post itself. And if a user wants to view all posts by particular author? Intuitive use might as well be '/posts/343/comments/23/author/posts/123/comments' ad infinitum :) Such problems can be solved by providing an endpoint for each distinct resource class and making it search provider. In your example case 3 endpoints are needed: /post, /comment, /author, all accepting other two as search parameters, e.g. /author?comment=123456 or /author?comments|id=123456 (inspired by FHIR).

andreasklinger 10y ago

my reasoning: you end up w/ a lot of filters very quickly and related post id will be just one of them also linking it to another resource usually involved expecting defaults (default ordering, default display, pagination etc) if you stay "flat" this tends to be less of an issue when usecases become more complex