This page explains the REST Adapter in Bridge context. If you were looking for the same information regarding the PAS Designer, refer to REST Adapter in the Designer guide.

REST (Representational State Transfer) is a way to provide access to web resources using a uniform and predefined set of stateless operations. Refer to the Wikipedia pages of Representational State Transfer for more information on REST.

The Bridge has a REST protocol adapter ready. It enables you to use any REST service as a backend for the Bridge.
Today, there are already many services, which speak REST. You may also have several Bridge services that speak together via REST (for instance as part of a Software Oriented Architecture (SOA) environment).
For more information on how to implement a Web service that speaks REST, refer to REST Service.

Importing the Web Service Interface

Each Web service has its own distinct interface: in case of a REST service, defined by the names of the resources, their operations and their parameters. Before an external Web service can be used, its interface definition must be imported to the UML model. With the Builder, you can import OpenAPI 2.0 Specification service descriptors encoded in YAML (Swagger) (for more information see Importing OpenAPI Files REST).

The example REST service used below comes from our REST examples:

On importing the OpenAPI of the example REST service REST_SupportManagerExample to a UML model, the Builder places the interface definition of the service in a service repository RESTService.SupportAPI.yaml. The nodes in that package are the graphical representation of the definitions in the OpenAPI file.

Figure: Imported RESTful Web Service

BRIDGE > REST Adapter > rest_imported_service.png

The REST service itself is displayed as an interface (SupportAPI). This interface features three resources (supportcases, customer and resolve) and their REST operations.
All input and output data structures are stored in a package Types.

Import Problems

The REST Service Only Provides a JSON Definition File

The xUML REST Importer can import YAML files only. If the service you want to call provides an OpenAPI file in JSON only, you can convert the JSON file to YAML before importing it. You can find many JSON to YAML converters on the internet.

The YAML File Does Not Set All Necessary Options

After having imported a YAML file, it may that some special options (like e.g. isVerbatimPath or externalName) that are not part of the official Open API description, are not set, but may be necessary.
Also, blob parameters, Blob Body Content Type/Reject Other Response Content Type and Accepted Request Content Type/Reject Other Request Content Types as described on Handling Blobs in the REST Interface are not supported by the importer.

In these cases, you will have to edit the import file manually to add blob parameters and set these options.

The Import of the YAML File Fails Or The REST Service Provides No Description File At All

It may be that the import of the YAML file fails or the REST service provides no description file at all. In this case, you can

draw the definitions manually by following the descriptions at Manually Providing the REST Interface ...
try an API design tool, the API Design Tool of Swagger. You can either check and rectify the YAML file here or write a new YAML file matching the service interface.

Accessing the Imported Web Service

An imported REST service can be accessed via a REST Adapter call as shown in the picture below.

Figure: REST Adapter Call

BRIDGE > REST Adapter > rest_adapter_call.png

Apply stereotype <<RESTAdapter>> to call REST services and assign an alias to provide a path to the service to be called.

BRIDGE > REST Adapter > rest_adapter_specification.png

The Operation property contains the REST operation to be called, means one of the imported REST operations, see Figure: Imported RESTful Web Service. The response of an REST adapter call can be either of complex type or a Blob.

An activity diagram like that will also be generated, if you choose option import to new model on importing the REST service description.
For a detailed overview on all REST parameters, refer to REST.

UML classes are mapped to the REST adapter call as described on XML - UML Class Mapping.

HTTP Headers

Builder 7.12.0 Runtime 2020.12 You can overwrite this default behavior by own header role definitions as described on HTTP Header Support > Overwriting the Standard HTTP Headers. In this context, you can also enable automatic header generation for dedicated headers.To do this, specify a list of header generation rules in tag requestHttpHeaderRoles on the REST alias.

requestHttpHeaderRoles can hold a list of definitions in format <http header name>:<role>. The listed headers will automatically be generated with the specified role for each adapter call on this alias. These definitions overwrite the default behavior, and X-Transaction-Id, X-Request-Id, X-Sender-Host and/or X-Sender-Service will be substituted by this definition.
Refer to REST Adapter Reference for the list of allowed values.

Also note the implications of Blob Body Content Type/Reject Other Response Content Type and Accepted Request Content Type/Reject Other Request Content Types as described on Handling Blobs in the REST Interface.

REST Adapter Components

The location of the REST service and other settings to access the service are provided in the component diagram on a REST alias. You can link these definitions in the component diagram to the implementation in an activity diagram via the tagged value alias on the corresponding activity.

Figure: REST Adapter Components

The REST service import provides an alias template you can derive the actual alias from (see picture above). Draw a new REST alias as described on Backend Components > Creating an Alias and draw a generalization from this alias to the template.

The <<RESTAlias>> can hold the following tagged values:

If you want to overwrite these tags dynamically during service execution, refer to Setting REST Request Options for more details.

OpenAPI 2.0 Specification