So I’ve been reading a lot on RESTfull design – specifically dealing with resources.
Taking the canonical example of Users, Posts, and Comments, with relationships as:
Users —(hasMany)—> Post —(hasMany)—> Comment
One may initially think to expose something like:
GET /users GET /posts GET /comments
POST /users POST /posts POST /comments
GET /users/id GET /posts/id GET /comments/id
PUT /users/id PUT /posts/id PUT /comments/id
DELETE /users/id DELETE /posts/id DELETE /comments/id
But then, say I want all Comments of a certain Post made by a particular User. I’d need to do something like:
GET /users/id
> someUser
> var postIds = someUser.posts()
GET /posts?id=<postIds[0]>&id=<postIds[1]>&...
> somePosts
> **application user inspects posts to see which one they care about**
> var postOfInterest = somePosts[x];
> var postId = postOfInterest.id;
GET /comments?id=postId
> someComments (finally)
Suppose though I only care about a Post or Comment in the context of it’s owner. Suppose a different resource structuring which may (or may not?) be more natural:
GET /users
POST /users
GET /users/id
PUT /users/id
DELETE /users/id
GET /users/id/posts
POST /users/id/posts
GET /users/id/posts/id
PUT /users/id/posts/id
DELETE /users/id/posts/id
GET /users/id/posts/id/comments
POST /users/id/posts/id/comments
GET /users/id/posts/id/comments/id
GET /users/id/posts/id/comments/id
GET /users/id/posts/id/comments/id
Which to me, is probably a better representation of what the resources are. Then all I need is:
GET /users/id/posts
> somePosts
> **application user inspects posts to see which one they care about**
> var postOfInterest = somePosts[x];
> var postId = postOfInterest.id;
GET /users/id/posts/postId/comments
> someComments
This just seems more like navigating a file system than the previous method – but I don’t know if its RESTfull at all (perhaps this is what REST was trying to get rid of) because in order to access a Comments resource, I need to know which User and which Post it belongs to. But the former requires 3 requests, while the latter requires just 2.
Thoughts?
1
As far as I know what you’re describing, essentially nested resources, is perfectly RESTful. You might want to keep the resources such as ‘/posts/id’ and ‘/comments/id’ in-case you want to get post/s or comment/s without knowing which user you’re looking at, but there’s nothing wrong with also nesting them inside each other for getting the posts for a particular user or comments for a particular post.
Rails in particular allows you to easily nest resources in this manner by doing something like the following in your routes configuration:
resources :users do
resources :posts do
resources :comments
end
end
1
When exposing a RESTful interface, you also need to examine, what the interface is telling the user.
When examining a post, its more than likely a user doesn’t care about who made it and unless post IDs are only unique in the scope of a user (which is unlikely) its just addtional cruft in the URL. While its true that a post has a user, I’m not so sure you can say that in this context it is owned by its user, if the difference is clear.
There is also the abiquity of what happens when user X writes a post, and user Y writes a comment on that post. In this /users/idZ/post/id/comment/id does idZ refer to the user who wrote the post, or the comment? Moreso, why do you need to know the user, if you already have a post or comment ID?
Alternatively, a comment is owned by its post, even if its ID is globally unique.
Lastly, there is a readability difference between users and user, with the latter implying discreteness. Similarly, with posts and post, and comments and comment.
So personally, given this, I’d use these actions (with the appropriate verbs where required):
ACTION /users
ACTION /user/id
ACTION /user/id/posts # A user owns these posts
ACTION /post/id # But the site owns this particular post
ACTION /post/id/comments
ACTION /post/id/comments/id
1
Colin, I guess the point you’re discussing is about nested REST and that is completely possible with the interface.
Users —(hasMany)—> Post —(hasMany)—> Comment
This relationship do exist, but how you defined them in next two cleared the purpose of nested representations. I designed this code under REST nested designs in this page as a demo reference, you can check them too.