The Bridge has a REST protocol adapter ready. It enables you to use any REST service as a backend for the E2E 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 E2E 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 E2E 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
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.
The E2E 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. 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. In this case, you will have to edit the import file manually to set these options. 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
The REST Service Only Provides a JSON Definition File
The YAML File Does Not Set All Necessary Options
The Import of the YAML File Fails Or The REST Service Provides No Description File At All
The E2E 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.
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. In this case, you will have to edit the import file manually to set these options.
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
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
Apply stereotype <<RESTAdapter>> to call REST services and assign an alias to provide a path to the service to be called.
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 (Bridge 7.1.0).
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 Service Reference.
Runtime 2019.9 xUML service adapters add the following HTTP headers containing correlation information to the request: Transaction id and request id will be logged to the transaction log on the adapter call. Having this information, you can use this for error analysis or usage metrics.
This header identifies the transaction the call belongs to. You can set the transaction id manually with setTransactionID. If not set, the Runtime will generate one.
This header will be passed through the callstack to identify all service calls that belong to a transaction.
This header identifies the unique request. The Runtime generates a unique number for each adapter call.
These headers contain the sender host resp. the sender service. They are set by the Runtime automatically.
Runtime 2019.9 xUML service adapters add the following HTTP headers containing correlation information to the request:
Transaction id and request id will be logged to the transaction log on the adapter call. Having this information, you can use this for error analysis or usage metrics.
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:
|additionalHeaders||This tagged value can contain a list of additional headers in form of name/value pairs.||Valid format is: <name>:<value>, e.g. |
|basePath||Specify here the base path of the REST service.||a valid path, e.g.|
|protocol||Specify here the protocol through which the REST service is accessible.||http, https|
Specify here whether you want the REST adapter to throw an exception upon receiving an HTTP error code >= 400.
|true (default)||Do not throw an exception upon receiving an HTTP error code >= 400.|
|false||Throw an exception upon receiving an HTTP error code >= 400.|
|host||Specify here the host running the REST service.||a valid host|
|port||Specify here the port through which the REST service is accessible.||a valid port|
|followRedirects||Specify here the maximum number of redirects to follow. Default value is 0 (no redirects).||any integer|
Use one of the following syntax rules:
|jsonKeepNulls||Builder 6.0.26 When jsonKeepNulls is true, attributes of the REST parameter having NULL values will be provided with the REST call, otherwise they will be left out completely (see also chapter NULL Values).||true||Render attributes with NULL values to the REST call.|
|false||Leave out attributes with NULL values in the REST call (default).|
|jsonCompact||Builder 7.0.0-beta3 When jsonCompact is true, the JSON composer will generate compact JSON, otherwise it will generate pretty JSON. jsonCompact defaults to true - also on re-compile of an older model with Builder as of 7.0.0-beta3.||true||Generate compact JSON (default).|
|false||Generate pretty JSON.|
|user||Specify credentials here, if the called REST service needs basic authentication. Other authentication algorithms have to be implemented manually via HTTP headers (see additionalHeaders and Setting REST Request Options).||Valid format is <user>/<password>, e.g. |
|Proxy Settings (if the called REST service is accessed via a proxy)|
|proxyType||Specify the proxy type.||See CURLOPT_PROXYTYPE.|
|proxyURL||Specify the URL of the proxy server.||See CURLOPT_PROXY.|
|proxyUser||Specify the proxy credentials.||See CURLOPT_PROXYUSERPWD, valid format is <user>/<password>, e.g. |
|SSL Settings (if the called REST service uses SSL)|
|sslCAInfo||Specify a file name containing additional certificates for the connection verification (e.g. additional root CAs).||See CURLOPT_CAINFO.|
|sslCertificateFile||Specify a fle name containing the client certificate.||See CURLOPT_SSLCERT.|
|sslCertificateType||Specify the type of the certificate.||See CURLOPT_SSLCERTTYPE.|
|sslPrivateKeyFile||Specify a file name containing the private key.||See CURLOPT_SSLKEY.|
|sslPrivateKeyPassword||Specify the password for the private key.||See CURLOPT_KEYPASSWD.|
|sslPrivateKeyType||Specify the type of the key.||See CURLOPT_SSLKEYTYPE.|
|sslVerifyHost||Specify whether to verify the host information form the SSL connection.||See CURLOPT_SSL_VERIFYHOST.|
|sslVerifyPeer||Specify whether to verify the peer information from the SSL connection.||See CURLOPT_SSL_VERIFYPEER.|
If you want to overwrite these tags dynamically during service execution, refer to Setting REST Request Options for more details.