4 ms·

Wouldn't most people disagree with: "not `/posts/343/comments` but `/comments?post_id=232`"?

• misterbwong 10y ago
  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
  Probably yes, the former not only "looks better", but is possibly easier to use in a view. Just spawn two delegates with `$post_path` and `pathcat($post_path, 'comments')` and be done with it. However, the argument being made here is that you may not want to expose post comments as sub-resource of a particular post, but rather as completely separate resource. And there is a point to that. Suppose you serve the post content as a static content, and comments from some application (octopress + disqus style). The latter format allows you to route anything matching `^/posts/(.*)` directly at web server level without touching application server at all. If you decided to use the former, then your infrastructure becomes dependent on your API structure. Not very nice :)