HTTP Methods in RESTful Web Services

In the previous articles, we covered REST Resource Naming Guide. In this post, we will discuss HTTP Methods in RESTful services. 

Introduction

RESTful services give the flexibility to create application involving following operations (also know as CRUD)

• Create
• Read/Retrieve
• Update
• Delete 

While performing these operations in RESTful services, there are guidelines or principles on using HTTP methods.These guidelines help us to choose correct HTTP methods for a certain type of operation.

It is highly recommended to follow these guidelines to make your REST API easy to read, follow and maintainable.

Below is the list of method that used while creating your RESTful API.

1. GET
2. POST
3. PUT
4. DELETE
5. PATCH

We will cover all of these HTTP Methods along with guidance for selecting correct method for your REST API operation.

1. GET Method

HTTP GET method used to retrieve information from the REST API.We should not use this method to change any information or the resource.GET should be idempotent, meaning regardless of how many times it repeats with the same parameters, the results are the same.

• Multiple requests should return same data for the GET request until some other processes change it (POST or PUT request).
• HTTP GET request should return 200(OK) Response if it finds data.

Let’s take some example of the GET request URI

• GET https://javadevjournal.com/customers   (retrieve all customers)
• GET https://javadevjournal.com/customers/1   (retrieve customer with ID 1)

2. POST Method

This method in the REST API should only be used to create a new resource.In some cases, POST method is used to update entity but this operation is not very frequent.POST API call is not idempotent nor safe and should be used with care.Let’s cover some extra points while using POST method in our REST API.

• HTTPS POST method calls are not cachable.We need to include Cache-Control or Expires header if we want to use cache for POST method.
• HTTPS POST must cause a cache to invalidate an entity.

Let’s take some example of POST method URI

• HTTPS POST https://javadevjournal.com/customers
• HTTPS POST https://javadevjournal.com/customers/1/addresses

HTTP/1.1 POST https://javadevjournal.com/customers/123
{
      //customer data
}

3. PUT Method

If we want to update an existing resource, PUT method should be used for this operation.PUT method has some features as compare to the POST method and we should keep those in mind

• PUT method is idempotent.This means the client can send the same request multiple time and as per HTTP spec, this has exactly the same effect as sending once. (This is for us to make sure PUT behaves correctly every time)
• Think of PUT method as putting a resource – This means completely replacing whatever is available at the given URL with the given data/ information.
• If a new resource created by PUT request, we should tell client by sending a correct response (<em>201</em> Created code).

idempotent is the main difference between the expectations of PUT versus a POST request.We need to follow this property while designing our REST API.

Let’s take some example of PUT method URI

• HTTPS PUT https://javadevjournal.com/customers/1/addresses/123 (Modify the address with an ID of 123)
• HTTPS PUT https://javadevjournal.com/customers/123

<span class="mceItemHidden">HTTP/1.1 PUT https://javadevjournal.com/customers/123
{
      “givenName”: “Java”,
      “surname”: Dev Journal
}</span>

4. DELETE Method

DELETE method should be used to remove a given resource.Similar to PUT method, DELETE operation is idempotent.If a resource is deleted any later request will change anything in the system and it should return 404 response.DELETE can be a long-running or asynchronous request.Let’s take some example of DELETE method URI

• HTTPS DELETE https://javadevjournal.com/customers/1
• HTTPS DELETE https://javadevjournal.com/customers/1/addresses/123

5. PATCH Method

Partial update to a resource should happen through PATCH method.To differentiate between PATCH and PUT method, PATCH request used to partially change a given resource while PUT used to replace existing resource.There are few things to keep in mind while using PATCH method.

• Support for PATCH in browsers, servers and web applications are not universal, this can post some challenges.
• Request payload for Patch is not simple and a client is required to send information to differentiate between the new and original documents.

Let’s have a quick look at HTTP Method Summary for RESTful API

HTTP Method	Operation	Comment
GET	Read Operation only	Uses only for the read operation.GET should be idempotent
POST	Create new resource	Should only be used to create a new resource
PUT	Update / Replace Resource	Update an existing resource.Think of PUT method as putting a resource
DELETE	Delete Resource	To remove a given resource.DELETE operation is idempotent
PATCH	Partial Update / Modify	Partial update to a resource should happen through PATCH

6. HTTP Status Codes

REST API uses the Status-Line part of the HTTP response to inform API client of their request’s overarching result. While designing our REST API, it’s is very important to send a correct response back to the customer.Response code help client in 

• Understanding status of the given request.
• It helps a client to take a correct step in the process.

As part of the RESTful design, we should clearly inform the client if they can move to next step or they need to take any corrective steps.HTTP defines over 40 standard status codes used to convey status back to the client.

A good status code also allows the developers to get their way out of the failed call.

All these status codes grouped into 5 different categories

Status Code Category	Description	Example
<span class="hiddenSpellError">1XX</span> - Informational	Informational indicates a provisional response	100 (Continue ) , 101
<span class="hiddenSpellError">2XX</span> - Successful	This class of status code indicates that the client’s request was successfully received, understood, and accepted.	200 (OK), 201(Created), 202 (Accepted)
<span class="hiddenSpellError">3XX</span> - Redirection	This class of status code indicates that further action required by the user agent to fulfill the request	301 (Moved Permanently), 302, 304
<span class="hiddenSpellError">4XX</span> - Client Error	The 4xx class of status code is intended for cases where the client seems to have erred	400 ( Bad Request), 401, 403, 404, 405
<span class="hiddenSpellError">5XX</span> - Server Error	Response status codes beginning with the digit “5” tell cases where the server is aware that it has erred or is incapable of performing the request	500 (Internal Server Error), 502, 503, 505

Before finishing this post, let’s cover some of the most commonly used HTTP statuses in the REST API.

6.1  200 (OK)

This status indicates the REST API successfully processes the request.200 response code include response body

• For GET request, 200 should contain requested resource.
• POST request should contain the result of the action performed (e.g new user-created).

6.2  201 (Created)

REST API should response with 201 response code when a new resource created in the collection.

6.3  202 (Accepted)

For the long-running process, REST API should return 202 as a valid response. 202 inform the client that request is accepted by the API but not yet completed.

6.4  301 (Moved Permanently)

301 status tell that request REST API resource has been moved to a new URI. As part of the 301 response, REST API should also include the new URI for the customer.

6.5  304 (Not Modified)

This indicates REST client that requested content has not been modified and if applicable, they can use cache copy of the content.Using this saves bandwidth and reprocessing on both the server and client.This is achieved by using added headers like If-Modified-Since or If-None-Match.

6.6  400 (Bad Request)

This is a generic error which indicates REST client that request does not meet the required criteria.The client should not repeat the request without changes.

6.7  401 (Unauthorized)

A 401 error response indicates that the client tried to run on a protected resource without providing the proper authorization.

6.8 403 (Forbidden)

A 403 error response indicates that the client’s request formed correctly, but the REST API refuses to honor it i.e. the user does not have the necessary permissions for the resource

6.9 404 (Not Found)

I will not explain this 🙂 

Summary

In this post of our REST with Spring Series, we discussed HTTP Methods in RESTful services.We discussed different HTTP method along with information about their use while building RESTful services. In the last part of our article, we discussed some of the commonly used HTTP status code for REST API.