Implementing an error handler in a REST API
Use the REST API Description view to implement error handlers in a REST API.
Before you begin
About this task
- Catch
- If an exception is thrown while processing a request in a subflow for an operation and that exception is not handled by that subflow, a message is routed to the Catch error handler. For example, if a JavaCompute node in the subflow for an operation throws an exception and that exception is not caught by a TryCatch node, that exception is passed to the Catch error handler.
- Timeout
- If a subflow for an operation is processing a message and that subflow does not respond to the client within the expected time limit, a message is routed to the Timeout error handler. The Timeout error handler can then be used to pass a response back to the client to inform that client that the operation has timed out. If this situation occurs, the subflow for an operation continues to process the message. The processing of that message is not canceled. However, a response to the client cannot be sent. Note: Depending on the client, the client might time out without receiving a response from calling the operation, in which case, any response that is sent is not received.
- Failure
- If an error occurs while the request from the client is being processed and that error is not handled by the Catch or Timeout error handlers, a message is routed to the Failure error handler.
Error handlers in a REST API are implemented as a subflow. You must use the IBM Integration Toolkit to create an empty subflow for each error handler. You can then implement the error handler by adding any of the standard message flow nodes that are available in IBM Integration Bus to the subflow.
If you do not implement an error handler, default error handling behavior is used. If you do not implement the Catch error handler or the Failure error handler, the exception is thrown back to the client with an HTTP 500 Internal Server Error status code. If you do not implement the Timeout error handler, a timeout exception is thrown back to the client with an HTTP 504 Gateway Timeout status code.
Procedure
To implement an error handler in a REST API, complete the following steps:
-
Open the REST API Description for the REST API for which you want to implement an error handler.
The REST API Description is in the Application Development view under the REST API project.
-
Locate the error handler in the REST API Description.
Error handlers are listed under the Error Handling heading.
-
Click the Implement the <error_handler_type> error handler link, where <error_handler_type> is the error handler type.
A new subflow is automatically created and opened. The link on the REST API Description changes to Open the <error_handler_type> error handler, and if you click the link, the existing subflow reopens.
- Implement the error handler by adding any of the standard message flow nodes that are available in IBM Integration Bus to the subflow.
Results
What to do next
- Use the REST API Description view to implement operations in a REST API, see Implementing an operation in a REST API.
- Secure your REST API by using HTTPS for encrypting communications between client and server, see Securing a REST API by using HTTPS.
- Secure your REST API by authenticating users with HTTP Basic Authentication, see Securing a REST API by using HTTP Basic Authentication.
- If your REST API is going to be used by client-side code that is running in a web browser, you might have to configure Cross-Origin Resource Sharing, see Permitting web browsers to access a REST API by using Cross-Origin Resource Sharing.
- REST APIs are configured by default to handle JSON data. If you want to handle non-JSON data, see Handling non-JSON data in a REST API.