What HTTP Status Code to Return


This is the fifth step in Design Restful API. In this post, we will learn what HTTP status code to return from REST API
In the previous post, we learned - 
When the client raises a request to the server through an API, the client should know the feedback, whether it failed, passed or the request was wrong. 

HTTP status codes are a bunch of standardized codes which has various explanations in various scenarios. The server should always return the right status code.

The following are the important categorization of HTTP codes:

2xx (Success category) These status codes represent that the requested action was received and successfully processed by the server.

  • 200 Ok The standard HTTP response representing success for GET, PUT or POST.
  • 201 Created This status code should be returned whenever the new instance is created. E.g on creating a new instance, using the POST method, should always return 201 status code.
  • 204 No Content represents the request is successfully processed but has not returned any content.DELETE can be a good example of this. The API DELETE /companies/43/employees/2 will delete the employee 2 and in return, we do not need any data in the response body of the API, as we explicitly asked the system to delete. If there is any error, like if employee 2 does not exist in the database, then the response code would not be of 2xx Success Category but around 4xx Client Error category.

3xx (Redirection Category)

  • 304 Not Modified indicates that the client has the response already in its cache. And hence there is no need to transfer the same data again.
4xx (Client Error Category) These status codes represent that the client has raised a faulty request.
  • 400 Bad Request indicates that the request by the client was not processed, as the server could not understand what the client is asking for.
  • 401 Unauthorized indicates that the client is not allowed to access resources, and should re-request with the required credentials.
  • 403 Forbidden indicates that the request is valid and the client is authenticated, but the client is not allowed access the page or resource for any reason. E.g sometimes the authorized client is not allowed to access the directory on the server.
  • 404 Not Found indicates that the requested resource is not available now.
  • 410 Gone indicates that the requested resource is no longer available which has been intentionally moved.

5xx (Server Error Category)

  • 500 Internal Server Error indicates that the request is valid, but the server is totally confused and the server is asked to serve some unexpected condition.
  • 503 Service Unavailable indicates that the server is down or unavailable to receive and process the request. Mostly if the server is undergoing maintenance.

Case Study 1

Appropriate HTTP status code is set in the response to be returned to the client. In this case study lets take Employee Management System(EMS) application. Let's analysis the EMS application and find out different resource operations. 

Consider we have Employee entity so let's Identify Resources from Employee entity using step 1After identifying the REST resources let's design the URL for REST resources by using step 2.

Let's apply below HTTP status code guidelines to return HTTP status code
  • When the request is successful, an HTTP status code indicating success or transfer (2xx or 3xx system) is sent as a response.
  • When the cause of request failure lies at the client side, an HTTP status code indicating client error (4xx system) is sent as the response. When a client is not responsible for request failure, however, when the request may be successful through a re-operation by the client, it is still considered as client error.
  • When the cause of request failure lies at the server side, an HTTP status code indicating server error (5xx system) is sent as the response.
Examples:

Method: Use GET method to retrieve employee object by id
Resource URL : /api/v1/employees/100
Return HTTP Status Code : 200 OK
-----------------------------------------------------------------------------------
Method: Use GET method to retrieve employees.
Resource URL : /api/v1/employees
Return HTTP Status Code : 200 OK
-----------------------------------------------------------------------------------
Method: Use POST method to post employee object
Resource URL : /api/v1/employees
Return HTTP Status Code : 201 Created
-----------------------------------------------------------------------------------
Method: Use PUT method to update employee object by id and pass employee object as JSON
Resource URL : /api/v1/employees/100
Return HTTP Status Code : 204 No Content
-----------------------------------------------------------------------------------

Conclusion

In this post, we learned what HTTP status code to return from REST API
It important to return appropriate HTTP status code in the response to be to the client.

Comments