REST Service Error Handling

REST services in general return errors via the HTTP status code, so first of all, you should carefully choose the status code you are returning on a service call. Besides the HTTP status code there is no standard way of how to provide additional error information with REST service implementations. Developers can return additional information in HTTP headers or body, though.

With the Bridge REST implementation, we decided to provide error information via the HTTP body by an error class or a Blob.

Defining Errors in the REST Service Interface

Default Error Class

Each REST port type should have a default <<RESTError>> class assigned. The Bridge will use this class as a default output in case of error.

Figure: Example REST Error Class

In case of error, this class should be

• filled with some error information and
• assigned to the REST HTTP response (so the error information will be returned to the caller)

The xUML Runtime will recognize attributes as error code and/or error message under the following conditions:

• if you applied the names code and/or message to these attribute(s)
• if you applied the stereotypes <<RESTErrorCode>> and/or <<RESTErrorMessage>> to these attribute(s)

In this case, Runtime error codes and/or messages will automatically by assigned to these attributes in case of error.

Specific Error Classes

You can define specific error classes for specific HTTP errors to provide more information on the error, or just return a Blob.

Figure: Specific Error Class

There is no difference between using an error class or a Blob. Assign the specific error class to related operations or REST resources via a <<use>> dependency having stereotype <<RESTResponseDefinition>>.

Figure: Assigning Error Class to REST Operations

On these <<use>> dependencies, you have to specify an HTTP status code on the name tag. For this status code, the default error class will be overwritten by the specific class.

You can apply the following name templates:

The definitions above are reflected in the OpenAPI service description (see (24.1) Defining a REST Service Interface#REST Response Definitions).

For responses of type Blob, you can additionally specify a blob body content type on the <<RESTResponseDefinition>> (tag blobBodyContentType). This information will be generated to the OpenAPI descriptor file and will set the the "Content-Type" header to this content type. Default content type is "application/octet-stream".

Refer to Implementing REST Operations for more information on error handling.

Implementing Error Handling

Each REST port type should have a <<RESTError>> class assigned. The Bridge will use this class as output in case of error (see Defining a REST Service Interface).

In the support manager example, REST port type SupportAPI has class RESTError assigned as error class.

Using function getRestHttpResponse(), you get access to the HTTP response object and can set the error details:

local response = getRestHttpResponse();
set response.responseObject = <my error object>;
set response.httpStatus = <HTTP status code>;

Assign the error object and a HTTP status code that corresponds to the error. This information will be returned via the HTTP response.

The xUML Runtime will recognize attributes as error code and/or error message under the following conditions:

• if you applied the names code and/or message to these attribute(s)
• if you applied the stereotypes <<RESTErrorCode>> and/or <<RESTErrorMessage>> to these attribute(s)

In this case, Runtime error codes and/or messages will automatically by assigned to these attributes in case of error.

In the support manager example, if user does not provide a support case id with the REST call, the implementation is as follows:

Error Handling for Specific Error Classes

If you defined a specific error class or Blob for a specific HTTP status code as described on Defining a REST Service Interface, you can use the same way as described above to provide the error details to the response. Provide the error details to an instance of the specific error class or Blob and provide the error class to the response object.
Look at activity Handle Authorization Errors of the support manager example: