In general, standardization of the JSON REST API RESPONSE is not specified, but to achieve efficiency, consistency and convenience, this standardization is needed.
We discovered and applied this achievement after working on many projects with common cases, so we concluded it became a standardization that we use to this day.
We are sure that for those of you who found this article, you already understand everything about JSON REST API RESPONSE, so we don't explain in detail about the little things related to it.
Our goal is efficiency, consistency and convenience
The methods and patterns that we use are always existing and common features, such as:
- HTTP Response Code (Wiki)
- Patterns for API Design (Microservice Api Patterns)
we only focus on RESPONSE DESIGN not on REQUEST methods and patterns.
The following is the standard HTTP Response Code that we use:
| CODE | DETAIL | GROUP |
|---|---|---|
| 200 | success for all actions including client requests, processes on the server (backend) and responses returned | success |
| 400 | error due to incorrect validate request parameters or payload | error |
| 401 | error due to lack of authorization | error |
| 403 | error due to not having access | error |
| 404 | error because data/service was not found | error |
| 500 | error on the server side, this response always sends an error reference code in the key error_ref. This reference code will later be used by the Backend Developer to look for errors in the server logs |
error |
The JSON response design that we use only has 2 main keys:
| Description | Keys | Details |
|---|---|---|
| Response Status | success, error |
- all responses with code 200 will have the key success - all responses with codes other than 200 will have the key error |
| Response Data | data |
This key is free to use to load the desired data whether the response status is successful or error Specifically for error code 500 there will be a key error_ref in the key data |
The is an example of its use:
Success Response
{
"success": "Success Messages ...",
"data": [...]
}
Error Response
{
"error": "Error Messages ...",
"data": [...]
}
Error Response 500
{
"error": "Error Messages ...",
"data": [
"error_ref": "XSADC",
...
]
}
Because of our principle of prioritizing simplicity in order to achieve ease in managing HTTP REST API responses from both the Backend and Frontend sides, all of this code is the code that we have encountered and is most frequently used and has strong relevance to general integration needs.
Because based on our experience, any successful action can be summarized in code 200 because the client side does not need information on what type of success they received.
Because the fewer main keys, the easier it will be for developers to define requirements and implement the use of programming code design.
Apart from that, the client only focuses on success and error responses where the information is already contained in the value of each key so that no other key is needed to explain why success or error occurred and for key data is the detail of the status, this pattern is very good for data consistency and bandwidth efficiency.
From the developer's side, this makes it easier to read the success or error status when a response is defined or obtained, this will be explained in the next section.
Because all errors are generally defined in the HTTP Response Code except error code 500
Error code 500 only indicates that an error has occurred on the server, therefore the server/backend only needs to send an error reference code in the form of a minimum of 5 capital character strings which will later be used to search for error details in the error logs.
Why not use numbers? because we don't need to define the error itself. This is not good for development, because there will be new code definitions for new errors.
Backend developers only need to create an engine that attaches a reference code to each error log generated, this is very good from a security perspective and ease of information from the client side, because the client does not need to know the details of the error that occurred from the server/backend side.
Why does it have to be in the main key data? because that's where the details of the status are.
| ❌ We Don't do this |
|---|
We do not use Design Response Methods and Patterns which usually include message, error_message keys and the like because this will waste bandwidth and be inconsistent in the design structure |
Generally in other Design Response Methods and Patterns they define a special error code in the form of a number, which is then sent to the client in the form of a separate key, for example error_code, error_number and the like, this is not efficient, unsafe and not easy to manage |
Hope it is useful.