Versions Compared

Old Version 2

changes.mady.by.user Kirstin Seidel-Gebert

Saved on

compared with

New Version 3

changes.mady.by.user Kirstin Seidel-Gebert

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Published by Scroll Versions from space WBRIDGE and version 21.2

...

Multiexcerpt
MultiExcerptNameREST_Errors_Introduction

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 (Bridge 7.1.0).

Multiexcerpt
MultiExcerptNameREST_Errors

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)
Multiexcerpt
MultiExcerptNameRESTErrorCodeAndMessage

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)
  • ifyou 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.

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

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

Info
iconfalse

Use this feature carefully. Having multiple error responses will possibly make your service confusing and will make it harder to implement service calls for a potential client.

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.

Info
iconfalse

You cannot overwrite HTTP response codes using REST Parameter classes (like e.g. 200).

You can apply the following name templates:

Example NameDescription
401A specific status code.The specific error class will only be used, if exactly this HTTP status code is send back.
40?, 4??Defining a status code pattern.The specific error class will only be used, if the HTTP status code that is send back matches the pattern.
???All status codes.This pattern defines a new default error class for the resource or operation. The specific error class is valid for all HTTP status codes.

The definitions above are reflected in the OpenAPI service description (see REST Response Definitions).

Info
iconfalse

Response definitions using patterns (like e.g. 40? or 4??) can not be generated to the OpenAPI file, so it is not recommended to use them. A response definition having pattern ??? will be generated as default response of the operation. Refer to REST Response Definitions for more information on this.

Bridge 7.1.0 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.