INTRODUCTION
REST Webservices(REST WS in short) are commonly used in the projects. In this article I will use Spring Boot to integrate several simple REST WS to the project. Since we will talk about the “Integration”, I will skip the creation of a Spring Boot project and show how to add REST WS to the existing Spring Boot project. I will then mention about how to do error handling for the REST WS.
CONTENTS
1. INTEGRATING REST WEBSERVICES TO THE PROJECT
____1.1. REST WS Integration on Spring Boot
2. REST WS ERROR HANDLING
____2.1. HTTP Status Codes
____2.2. Default Spring Boot REST WS Error Handling
____2.3. Using Custom Exception Mapped to a Proper HTTP Status Code
____2.4. Using Custom Exception with Custom Error Fields
____2.5. IETF RFC7807 Standard for REST WS Error Structure
3. CONCLUSION
4. REFERENCES
1. INTEGRATING REST WEBSERVICES TO THE PROJECT
REST WS can be integrated to the project with various ways, such as Apache CXF, Jersey etc. But also the integration by Spring Boot is relatively robust and easy. In this article the framework to integrate REST WS will be Spring Boot.
1.1. REST WS Integration on Spring Boot
To Integrate REST WS to a Spring Boot project, there is a necessary dependency to be added on pom.xml file:
2. REST WS ERROR HANDLING
SOAP Webservices has built-in error handling, so the error comes within Fault element with all the details. However in REST WS the error handling is only through HTTP status codes unless it is especially implemented.
2.1. HTTP Status Codes
When a request is made by the client to a HTTP Server, the server informs the client whether the request is handled successfully. This information is represented with 5 categories of status codes:
- 100-level (Informational) — Server acknowledges a request
- 200-level (Success) — Server completed the request as expected
- 300-level (Redirection) — Client needs to perform further actions to complete the request
- 400-level (Client error) — Client sent an invalid request
- 500-level (Server error) — Server failed to fulfill a valid request due to an error with server
To handle the errors, the first step is to provide the client the proper code. On the response, the additional information will be also indeed helpful.
Several commonly used response codes are:
- 200 OK: The HTTP status code 200 asserts that the request was successfully handled.
- 304 Not Modified: Indicates that the resource has not been modified.
- 400 Bad Request: Client sent an invalid request — such as lacking required request body or parameter
- 401 Unauthorized: Client failed to authenticate with the server
- 403 Forbidden: Client authenticated but does not have permission to access the requested resource
- 404 Not Found: The requested resource does not exist
- 412 Precondition Failed: One or more conditions in the request header fields evaluated to false
- 418 I’m a Teapot: Indicates that the server refuses to brew coffee because it is, permanently, a teapot.
- 500 Internal Server Error: A generic error occurred on the server
- 503 Service Unavailable: The requested service is not available
5xx errors shows that exceptions is thrown by the server while handling a request. However, the clients do not care internal errors. Therefore, to reduce such kind of responses to the client, the internal errors should be handled or caught and then response should sent with another proper status code. For example, if an exception occurs because a requested resource doesn’t exist, we should expose this as a 404 rather than a 500 error. On the other hand, this does not mean that 5xx should never be returned. In cases of unexpected cases such as service outage, a 5xx status code is the proper one.
2.2. Default Spring Boot REST WS Error Handling
Spring Boot has a default exception handling for REST WS. Assuming that there is an REST WS as “Adressbuch” to manage contact information(similar to contacts on the phones). Lets also assume that this API throws an error if there is not any adressbuch entry with a given name, it throws an error.
In this case the default exception handling will be:
As it can be seen, the default exception handling by Spring Boot has 5 elements in response.
- Timestamp of the occurrence of the error
- HTTP Status code
- Title which is shown on “error” field
- Message that is empty as default
- URL path on where the error is happened.
These information helps to the client of software engineers to solve the problem.
2.3. Using Custom Exception Mapped to a Proper HTTP Status Code
In our case, Spring Boot returned 500 Internal Server Error. It would be better to provide the most specific error code if possible. Therefore instead of 500 Internal Server Error, 404 Not Found can be used.
On the implementation a custom exception can be mapped to HTTP 404 Not Found, such as:
Then it can be used instead of IllegalArgumentException on line 35:
This will lead to a better way of showing the error:
2.4. Using Custom Exception with Custom Error Fields
In most cases, more information can be provided with the error response body. Such as:
- Error — A unique identifier for the error
- Message — A brief human-readable message about the error
- Detail — The explanation of the error in detail
- url — A URL in which more information can be found
To achieve that goal an exception handler and a POJO can be created as well as other various changes:
These changes will result such error response structure:
Although it is also possible to return a list of errors, it is better to return the most important error in most cases.
While most of the REST APIs has a similar structure for the exception handling, they usually do not have a standardized structure. This causes harder to achieve uniformity of exception handling by the libraries, frameworks, applications etc.
2.5. IETF RFC7807 Standard for REST WS Error Structure
The IEFT designed RFC 7807, that creates a uniform error-handling schema to standardize REST API error handling. This schema is composed of five parts:
- type — A URI identifier that categorizes the error
- title — A brief, human-readable message about the error
- status — The HTTP response code (optional)
- detail — A human-readable explanation of the error
- instance — A URI that identifies the specific occurrence of the error
Instead of using the previous custom error response structure, the structure of RFC 7807 can be used. After a few changes on the example project:
The error response becomes:
3. CONCLUSION
In this article several approaches on REST WS error handling is covered, such as:
- Default Spring Boot error handling
- Giving specific status codes on 5xx errors
- Providing additional information in response bodies
- Error handling with a uniform approach
Unlike SOAP Webservices, exception handling does not come out of the box on REST WS. Even if Spring Boot implements REST WS exception handling at some degree, it is also possible to create a custom error response structure. Moreover, a standardized structure such as RFC7807 can be used.
The code can be found at:https://github.com/unl40/REST-WS-Spring-Boot-Integration-and-Error-Handling
4. REFERENCES
https://www.tutorialspoint.com/spring_boot/spring_boot_building_restful_web_services.htm
https://www.baeldung.com/rest-api-error-handling-best-practices
https://www.baeldung.com/spring-mvc-controller-custom-http-status-code
https://www.baeldung.com/exception-handling-for-rest-with-spring
https://en.wikipedia.org/wiki/List_of_HTTP_status_codes
