RESTFUL WEB SERVICES - Java EE Design Patterns - page 172

ID. On successful creation, the HTTP response is 201 (CREATED) , and a link to the newly created
resource is returned either in the Location header of the response or in the JSON payload of the
response body. The resource representation may be returned in the response body. This is often
preferable to avoid making an additional call to the API to retrieve a representation of the data that
had been just created. This reduces the chattiness of the API.
In addition to the HTTP response codes to a GET request, a POST can return 204 (NO CONTENT) if
the body of the request is empty. A well‐formed URI that you might use in your forum application
could be POST users , with a request body containing the new user's details or POST users/123456/
posts to create a new post for the user 123456 from the data in the request body.
PUT
The PUT method is most commonly used to update a known resource. The URI includes enough
information to identify the resource, such as a context and an identii er. The request body contains
the updated version of the resource, and if the update is successful, it returns the HTTP response
code 200 . A URI that updates a user's information is PUT users/123456 . Less commonly, you can
use the PUT method to create a resource if the client creates the identii er of the resource. However,
this way of creating a resource is a little confusing. Why use a PUT when a POST works just as
well and is commonly known? An important point to note about updating a resource is that the
entire representation of the resource is passed to the service in the HTTP body request, not just the
information that has changed.
DELETE
Surprisingly, you use this method to delete a resource from a service. The URI contains the
context and the identii er of the resource. To delete a user with the ID 123456, you use the URI
DELETE users/123456 . The response body may include a representation of the deleted resource. A
successful deletion results in a 200 (OK) HTTP response code being returned; if the resource is not
found, a 400 code is returned.
REST IN ACTION
You are going to design the RESTful API for a forum site using what you have learned so far.
You start by examining the data structure of the site and identifying the data domains. The two
main domains are users and posts. Users can be further analyzed into followers, and posts are often
organized under topics. So with these domains, start thinking about the URI you need to represent
these resources.
The users noun
To create a new user, you know that you must use POST and the users context, so a URI that creates
a user would look like this:
POST /users