RESTFUL WEB SERVICES - Java EE Design Patterns - page 174

because you have no context. There is not enough information for the service to create a post
because you don't know to which topic the post should be associated.
To get a topic and a post, use:
GET /topics/123
To get a specii c post under a topic, use:
GET /topics/123/posts/456
or
GET /posts/456
To delete a topic or a post, use:
DELETE /topics/123
To delete a post, use:
DELETE /topics/123/posts/456
or
DELETE /posts/456
To amend a post or a topic, use can any of the following three methods:
PUT /topics/123
PUT /topics/123/posts/456
or
PUT posts/456
Now that you have the simplest URIs and contexts dei ned, you can start to have some fun and
combine the users, topic, and post to make them more complicated.
To retrieve a representation of all topics posted by a given user, use this:
GET /users/123456/posts
To get all posts under a given topic for a given user, use this:
GET /users/123456/topics/123/posts
To get all posts by a follower of a given user of a given topic, use this:
GET /users/123456/followers/456789/topics/123/posts
You can be creative with your combinations of resource. Despite the seemingly complicated nature,
you must never forget that the clients of the RESTful API use the URIs, so the URIs should be easy
to understand, and nesting should be kept to a minimum. If you feel that your URI is so complicated
that it should be accompanied by an explanation, you should consider refactoring it.
An example of a well‐designed and thought out RESTful API has been implemented by the cloud
storage company Sugarsync ( https://www.sugarsync.com/developer ). I r ecommend that you
review their resource reference to see how they clearly dei ne the folder, address, and workspace
resources. Note how the HTTP methods are used to create, read, and delete resources.