Restful APIs, based on HTTP protocol, are becoming increasingly popular among developers, especially after microservices have been rising in popularity in the past 4-5 years. The SOAP-based APIs, used in Service Oriented Architecture, had been popular since the year 2000.
But over time with the increasing complexity of the software application and the growing popularity of microservices, REST APIs are becoming the de facto standard to cater to the complex needs of today’s software development.
While calling these REST APIs, the client should properly understand what happened to his request. Did it succeed or failed? If it failed, then what went wrong?
This information helps clients to handle the response properly and build a better user experience around them. The responses from the APIs should be an important part of your API design process.
Now that you know just how vital API response codes are let us take a closer look at them. With this article, you will better understand which response codes to integrate into your REST API design.
Overview of HTTP Error Codes
HTTP consists of over 70 codes to deliver the outcome of a client’s request. Here are the five categories of these codes:
- 1xx: Informational – Signals transfer protocol-level information.
- 2xx: Success – Successful acceptance of client’s request.
- 3xx: Redirection – Additional action from the client’s end to complete the request.
- 4xx: Client Error – Error status codes pointing at clients.
- 5xx: Server Error – Error status codes pointing at the server.
Understanding Response Codes
To make sense of response codes, first, you need to use them right. There might be over 70 HTTP codes, but most developers do not memorize all of them. The efficient way to use HTTP response codes is to keep them in a small subset.
What is the Ideal Number of Codes?
The magic number for codes will vary from developer to developer. However, to begin with, think of the results of the interaction between API and an app. There can typically be only three:
- It works.
- The application makes a mistake.
- API makes a mistake.
What does this mean? Well, to put it simply, you can start with as little as three codes. Ensure to use the following:
- 200 – OK
- 400 – Bad Request
- 500 – Internal Server Error
Once you add these three essential codes, you are free to add others you require. That said, it is best not to go beyond a total of eight.
Response Code Rules
When deciding which codes to use, you also want to remember specific rules related to them. Here are a few of them:
- Do not use 200 (OK) to communicate errors. Never compromise a Rest API merely for the comfort of less sophisticated clients. Use codes the right way and according to their specification.
- Use 400 (Bad Request) for non-specific failures. For general client errors, the 400 code is appropriate. Typically, you use this code when no other 4xx error code fits the bill. Errors in the entire 4xx subset can explain the client’s mistake in the response body.
- Use 500 (Internal Server Error) for API malfunction. A 500 error can never be a mistake on the part of the client. For this reason, users will often retry the same request that caused the response in the first place. This code is the general Rest API error response, occurring when web frameworks deal with unusual request handler codes.
The best way to make sense of your Rest APIs’ codes is to reduce them in number. Keep their subset short and sweet and expand your knowledge on these codes as much as you can. That includes being aware of the dos and don’ts of these responses.
The actual choices of codes, however, boils down to personal preference and intuition.
Not sure which codes work for you and which do not? Please leave it to us! Our team will have your app and websites making optimum use of error codes to help you and your clients.
Along with ensuring correct response code, you should avoid these 7 mistakes to ensure your REST APIs can be consumed easily.
Enjoyed this article? Subscribe for more valuable and great content !