Javarevisited: Top 10 HTTP Status Code Every RESTful web Service Developer Should know

A good knowledge of HTTP protocol is must for a RESTful Web Service developer because REST uses HTTP principles and a good portion of its popularity is due to HTTP itself. One of the important part of HTTP is the status code, which gives useful information related to client request. They are also known as HTTP response code because they are sent in header on HTTP response by Server to indicate what happened with client's request. The status codes ranges from 100 to 500 but not all of them are valid and useful. Instead the first number e.g. 1xx or 2xxx denotes the class of status codes.

The HTTP response codes are divided in 5 major classes where 1xx represents informational codes, 2xx represents success codes, 3xx represents redirection codes, 4xx represents client error code and 5xx represent server error codes.

Since it's not practical remember all the status code, I'll list some of the important HTTP status code from RESTful API point of view.

10 HTTP Response Codes Every Developer Should Learn

If you are a Java developer who is either developing a RESTful Web service or a REST client, you can benefit a lot from knowing these important HTTP status codes. I'll also give you some insight about which codes you can use in response for creating resources, updating resources and deleting resources in RESTful API.

1XX Informational Codes

The 100 series of HTTP codes are informational code and I have never used them while developing RESTful web services. Some of the useful 1XX series of status code is 100 - Continue and 101 Switching Protocols which is used by client to ask Server to switch protocol and server agrees to do that. From REST API point of view, you hardly use 100 series of status code.

2XX Success Codes

The 200 series of HTTP response codes are used to indicate success, which means client's request is successfully received and processed by Server.

200 - OK

This is one of the most common HTTP response code. Most of the HTTP response contains this code, which indicates that request is received and successfully processed. If you don't any better HTTP code to respond with a successful request, you should send 200 - OK to the client.

201 - Created

This is another common HTTP status code which indicates that a resource has been created successfully in server because of the client's request. This also indicate that request was received and processed successfully.

You can use this status code to respond when client send HTTP POST request to create a RESTful resource e.g. sending a POST request to create a book on https://bookstore.com/api/books.

Even though you can use 200- OK to respond, 201 - Created is more specific and has become an standard while responding POST messages which is used to create resources.

204 - No Content

This is another success status code which indicates that response body is empty. Similar to previous codes it also indicates that the request has been received and processed successfully. You can use this code to respond to DELETE calls on your REST API.

Since DELETE is used to delete a resource in server there is not really any content to send on response body. By sending 204 - No Content you inform client that there is not really any content on response body. Though you can also send 200- OK but 204 - No Content is more specific.

3XX Redirection Codes

The 300 series of HTTP status code indicates the client must take additional action to complete the request. Many of these status codes are used in URL redirection.A user agent e.g. brosser may carry out the additional action with no user interaction only if the method used in the second request is GET or HEAD.

A user agent may automatically redirect a request. A user agent should detect and intervene to prevent cyclical redirects, many browsers like Chrome and Firefox does that.

301 - Moved Permanently

This code indicates that this and all future requests should be directed to the given URI. You can use this status code when you release a new version of your REST API or when a client hit an obsolete or deprecated URI.

304 - Not Modified

This code indicates that the resource has not been modified since the version specified by the request headers If-Modified-Since or If-None-Match. In such case, there is no need to retransmit the resource since the client still has a previously-downloaded copy.

This is particularly useful for collection URIs, for example if a client just downloaded list of books from https://bookstore.com/api/books and server responded with thousands of books, you can send 304 if you see the same request coming again.

This can potentially save Server from exhausting resources for full filing repeated requests. It can also prevent DOS (Denial of Service) attack.

4XX Client Error Codes

The 400 series of status code represent client side error e.g. a bad request, an unauthorized request or requesting for a resource or page which doesn't exists in the server. In fact, the most popular HTTP status code 404 - Not Found comes from this category, which indicates page not found error. Other useful codes from this category is 400 - Bad Request, 401- Unauthorized and 403 - Forbidden.

400 - Bad Request

This status code tells the client that format of request is invalid. For example, if you are sending JSON in request body to create a new resource and that JSON is not valid then you can return 400 - Bad Request. If JSON is valid, then you can send 201 - Created.

401 - Unauthorized
This HTTP status code indicates that client is not authorized.

403 - Forbidden
This HTTP response code indicates that even though client is authorized it is not allowed to access that particular resource.

404 - Not Found
This status code indicates that client is asking for a resource which doesn't exists in server. This could happen due to typo in URL etc. You can send this code in response to GET resource if resource doesn't exists.

5XX Server Error Codes

The 500 series of error code indicates server side error, for example, if you get an exception while processing client request e.g. NullPointerException or ArrayIndexOutOfBoundException in Java based server then you should respond with 5XX status code.

This code indicate that the request was ok, it was just the server which couldn't process the request, if request were invalid, you would have received 400 - Bad Request error code.

500 - Internal Server error
The most important and I guess the only important code in this category is 500 - Internal server error. If you get a RuntimeException while processing a client request, you should return this code as part of response. The response body can have more details about error.

Though you should be careful that you don't leak sensitive information on stack trace e.g. client name or sensitive details. Even leaking which version of Tomcat or Apache your server is running can compromise security of your web application.

This is extremely important for all client facing, external Java application. These kind of issues are generally identified during penetration testing, but you can be proactive and employ secure coding practices to minimize such mistakes. You can read Iron Clad Java to learn more about security loopholes and secure coding in Java.

And, here is a full list of HTTP status codes which you an print and keep it handy for reference:

That's all about some of the important HTTP status code for RESTful Web Service developers. Even if you are not working on REST, a good knowledge of HTTP goes a long way in general. I strongly believe that every web developer be it a Java developer or a JavaScript developer should read a good book on HTTP e.g. The Definitive guide of HTTP to fill the gaps in his understanding and get himself familiar with the essential HTTP concepts. It's one of the most useful investment you can make to improve your knowledge about web and web services.

Other Java and REST Articles and tutorials you may like

Javarevisited

Thursday, March 14, 2024

Top 10 HTTP Status Code Every RESTful web Service Developer Should know