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 standard REST service implementations. Developers can return additional information in HTTP headers or body, though.

With the Designer 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

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

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 REST Error Code and/or REST Error Message to these attribute(s)

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

Implementing Error Handling

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

In the support manager example, REST port 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 REST Error Code and/or REST Error Message 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 the API user does not provide a support case id with the REST call, the implementation is as follows:

create error;
set error.code = "400"; 
set error.message = "Bad Request: id missing.";

local response = getRestHttpResponse();
set response.responseObject = error;
set response.httpStatus = 400;