Rest API response codes and rfc 7807 specification using Spring Boot.
In this tutorial, I will talk about Rest API response codes, when to use which response code and RFC 7807 specification when returning an error. I will use a simple REST Api which is implemented using Spring Boot. This API will be responsible for Customer CRUD operations with some real business cases.
- Let’s create the customer-service application. This application will expose customer related APIs for GET, POST, UPDATE and DELETE Http methods. I used an H2 database to store the customer entities. You can import the application from following Github repo.
Application will be running on port 3001 and you can reach the H2 database via http://localhost:3001/h2-console.
2. Response codes are simply the result of the client requests. Since these response codes are part of a agreed protocol between the clients and API provider, we may think that response code do not matter too much. However, most of the tools (running behind the scenes) which are part of request and response traffic rely on these response codes. Hence, providing correct response code is extremely important.
To make things simple, I will only use 200 OK, 201 CREATED, 202 ACCEPTED, 404 NOT FOUND and 400 BAD REQUEST, responses but I hope I will be able to give the business cases behind these response codes. You can find the sample calls under the resources\api_calls_postman folder.
2.1 Request: GET - localhost:3001/api/v1/customer
Business case: Requested entity/entities are searched. The result is returned. The result may contain some customers or not. Here, we should not use 404 NOT FOUND response even if no customer is found. Because client is not quering a particular entity.
Response code: 200 OK
2.2 Request: GET localhost:3001/api/v1/customer/customer_no_2
Business case: Requested a single entity with customer no. Customer is found.
Response: 200 OK
2.3 Request: GET localhost:3001/api/v1/customer/non_existing_cus_no
Business case: Requested a single entity with customer no. Customer is not found.
Response: 404 NOT FOUND
2.4 Request: GET localhost:3001/api/v1/customer/xx
Business case: Requested a single entity with customer no. Customer no is too short. Customer no is not validated and it is not in expected format.
Response: 400 BAD REQUEST
2.5 Request: POST localhost:3001/api/v1/customer
Business case: Customer is created.
Response: 201 CREATED
2.6 Request: POST localhost:3001/api/v1/customer/endofyear
Business case: Request is accepted without any errors. Long running batch operation is started. Here we should use 202 ACCEPTED instead of 200 OK. Server accepted the request but did not completed the functionality yet.
Response: 202 ACCEPTED
2.7 Request: POST localhost:3001/api/v1/customer
Business case: Customer data has some errors. This is a data validation issue.
Response: 400 BAD REQUEST
3. Addition to response codes, if API will return an error, simply returning an error code is not sufficient. For this purpose, RFC 7807 is developed. This specification provides a meaningful way to give detailed information about the error. You can find more details on https://www.ietf.org/rfc/rfc7807.txt.
For RFC 7807 implementation, I have used org.zalando.problem.Problem class. You can find the dependency in pom.xml file.
You can see some exception definitons in the com.horasan.customer.rest.error.exceptions package. These exceptions are used as a result of business validations.
CustomerRestExceptionHandler class in the com.horasan.customer.rest.error package is annotated with @RestControllerAdvice so that I handled the exceptions here and prepared error responses according to RFC 7807.
3. A bit more on RFC 7807. This specification defines an error with type, title, detail and status properties. I think type is the most useful property in this approach. Because we can use this area for providing detailed information about the specific error. I used this field as a link to the related business validation error. You can find the GET method handlers in ErrorController class.
In this tutorial I tried to provide some basic information about the Rest API response code and RFC 7807 specification with a Spring Boot application. Thanks for reading…
