RESTFUL WEB SERVICES - Java EE Design Patterns - page 171

Plural Not Singular
Resource names should be plural because they represent collections of data. The resource name
users represents a collection of users, and the resource name p osts represents a collection of posts.
The idea is that plural nouns represent a collection in the service, and the ID refers to one instance
within that collection. It may be justii able to use a singular noun if there is only one instance of that
data type in the entire application, but this is quite uncommon.
HTTP Methods
There are eight HTTP methods dei ned in Hypertext Transfer Protocol 1.1; however, only
four are commonly used when designing RESTful APIs. They are GET , POST , PUT , and DELETE .
These methods have specii ed meanings and usages within the context of REST. The concept
of idempotency is especially important when considering the HTTP method. The meaning of
idempotency from a RESTful API point of view is that a call repeatedly made by a client to the same
URI will always produce the same result. So making one request produces the same outcome, on the
server, as the request made multiple times. (This assumes that a different and separate operation has
not changed the resource's state.)
Only one of the four most commonly used methods is idempotent: GET . This means that any
resource URI that is executed with this method cannot effect change on the server. You cannot use
it to create, update, or delete a resource. The HTTP 1.1 specii cation refers to this method as safe
because it “should not have the signii cance of taking an action other than retrieval.” In the context
of REST, this method is used for getting a resource's representation from the server. It must never be
used to make changes to data.
The other three methods— POST , PUT , and DELETE —are not idempotent methods and are expected
to effect change on the server. You'll learn about each method and how to use it in the context of
a forum site. You'll also learn about the HTTP response codes ( http://www.w3.org/Protocols/
rfc2616/rfc2616‐sec10.html ) that can be returned, along with the responses to the client and
what they mean.
GET
You use this method to get resource representations from the service. You should never use it
to update, delete, or create a resource. Calling it once should have the same effect as calling it
100 times. If the resource requested is successful, the representation of the resource is returned in
the body of the HTTP response in the requested data format, which commonly is either JSON or
XML. The HTTP response code returned is 200 (OK) . If the resource is not found, it should return
404 (NOT FOUND) , and if the resource request is badly formed, it should return 400 (BAD REQUEST) .
A well‐formed URI that you might use in your forum application could be GET users/123456/
followers , which represents all the followers of the user 123456 .
POST
You use the POST method to create a new resource within the given context. For example, to create
a new user, you would post to the users resource the data necessary for a new user to be created.
The service takes care of creating the new resource, associating it to the context, and assigning an