Once the resources have been identified, these are next set of questions to ask: • What would a consumer like to do with the resource?
• What aspects of the resource would be of interest to a consumer?
The answers to these questions identify the HTTP verbs to be used for each of the identified resources.
HTTP verbs form an important part of a RESTful API design. They identify the actions to be performed on a resource. A consumer’s actions with a resource can be mapped to an HTTP verb in most cases; for example, creating a product can be done using the HTTP verb POST. The primary and most commonly used HTTP verb are POST, GET, PUT, and DELETE. These verbs perform the CRUD operations on the resource as follows:
• POST verb creates a new instance of the resource • GET is used to read
• PUT is used to update • DELETE is used to delete
There are other verbs—such as HEAD, OPTIONS, TRACE, and CONNECT—in the HTTP 1.1 spec. Let’s look at the detailed usage of these verbs in the design of a REST API interface in the next few sections of this chapter.
GET
The GET verb is used by the client to retrieve information about the requested resource entity identified by the request URI. Requests using GET should only retrieve data and should never modify the data in any way. The GET request is considered safe. GET is a read-only method and does not make any changes to the resource data. Hence, it can be used without risk of data modification or corruption. Also, calling the GET method on a resource once has the same effect as calling it multiple times. Hence, the GET verb is
idempotent and safe.
If the request has been executed successfully, the server returns the requested data normally in XML or JSON, depending on the format requested by the client. The HTTP ‘Accept’ header is used by the client to specify the expected format of the response. The request may contain additional HTTP headers that can control the data returned by the server in response to the GET request. For example, if the request message includes headers such as If-Modified-Since, If-Unmodified-Since, If-Range, If-Match, or
If-None-Match, it is processed as a conditional GET method. The server responds with the
entity only if the conditions described by the header field(s) are satisfied. The conditional GET method is used to reduce unwanted network usage. These conditional headers are inspected by the server to determine if the client is already in possession of some of the data it is requesting. Data is returned only if the condition is satisfied; otherwise, no data is transferred in the response. Thus, conditional GET headers help reduce network traffic.
On successful execution of the GET request, the server responds with HTTP
response code of 200 OK. In the event of an error, the server usually responds with the 404
Not Found or 400 Bad Request status code.
The following are examples of GET request for a resource: GET https://www.foo.com/customers
POST
The POST verb is normally used to create a new resource. In particular, it is used to create a subresource, which is subordinate to the parent resource identified by the request URI. To create a new resource, send a POST request to the URI of the parent resource and the server takes care of creating the new resource as a subresource of the parent, based on the information provided in the payload. Each new resource created is assigned a name or an ID to uniquely identify it. This identifier may be used to retrieve the resource information using a GET request at a later time.
On successful execution of the POST request, the origin server should respond with a 201 Created status code. The response payload should contain the details of the resource created in a format expected by the client. The response should also contain a
'Location' header to specify the location of the newly created resource. If the resource
cannot be created, the server may respond with a 204 No Content status code. POST is neither safe nor idempotent. It is therefore recommended for non-
idempotent resource requests. Making two identical POST requests usually results in two resources containing the same entity.
The following is an example of a POST request to create a 'customer' resource: POST http://www.foo.com/customers HTTP/1.1
{
"customers": {
"customerId": "12345", "customerName": "Brajesh De", "Address":{ "AddressLine1":"206 Lane 1", "AddressLine2":"22 Cross", "City":"Bangalore", "State":"Karnataka" } } }
PUT
The PUT method is generally used to update an existing resource entity identified by the request URI. If the resource identified by the request URI exists, then the message payload should be considered as the changed version of the existing resource entity. If the resource does not exist, and the URI is capable of being defined as a new resource, the server can create a new resource with the information provided in the message payload. On successful execution of the PUT request, if a new resource is created, the server must respond with a 201 Created status code. If an existing resource is modified, the server must respond with either the 200 OK or the 204 No Content status codes to indicate successful execution of the request. In the event of errors in modifying or creating a PUT request, the server should respond with an HTTP error response status code and an error message that indicates the nature of the problem.
PUT is idempotent but not safe. This means invoking the PUT method multiple times with the same request payload has the same effect on the resource—it continues to exist in the same state. But since the PUT method updates the resource entity, this method is not safe.
The following is an example of a PUT request. PUT http://www.foo.com/customers/12345 HTTP/1.1 {
"customers": {
"customerId": "12345", "customerName": "Brajesh De", "Address":{ "AddressLine1":"206 Lane 1", "AddressLine2":"22 Cross", "City":"Bangalore", "State":"Karnataka" } } }