Page tree
Skip to end of metadata
Go to start of metadata

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

Example File (Builder project Add-ons/REST):

<your example path>\Add-ons\REST\uml\accessSupportManager.xml

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:

Example File (Builder project Add-ons/REST):

<your example path>\Add-ons\REST\uml\supportManager.xml
<your example path>\Add-ons\REST\uml\supportManager_auth.xml

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.

Import Problems

The REST Service Only Provides a JSON Definition File

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.

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. In this case, you will have to edit the import file manually to 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

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.

HTTP Headers

Runtime 2019.9 xUML service adapters add the following HTTP headers containing correlation information to the request:

  • X-Transaction-ID
    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.
  • X-Request-ID
    This header identifies the unique request. The Runtime generates a unique number for each adapter call.
  • X-Sender-Host and X-Sender-Service
    These headers contain the sender host resp. the sender service. They are set by the Runtime automatically.

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:

AttributeDescriptionAllowed Values
additionalHeadersThis tagged value can contain a list of additional headers in form of name/value pairs.Valid format is: <name>:<value>, e.g. API-Key:e2e. Separate multiple headers with a comma.
basePathSpecify here the base path of the REST service.a valid path, e.g. /support
protocolSpecify here the protocol through which the REST service is accessible.http, https
ignoreHttpErrors

Specify here whether you want the REST adapter to throw an exception upon receiving an HTTP error code >= 400.
For older models, if this flag is not present, it will be considered false.

ignoreHttpErrors can be overridden via the request options (see Setting REST Request Options).

true (default)Do not throw an exception upon receiving an HTTP error code >= 400.
falseThrow an exception upon receiving an HTTP error code >= 400.
hostSpecify here the host running the REST service.a valid host
portSpecify here the port through which the REST service is accessible.a valid port
followRedirectsSpecify here the maximum number of redirects to follow. Default value is 0 (no redirects).any integer
options

Specify native cURL options as listed in Setting cURL Options on the URL Adapter .

Use one of the following syntax rules:

  • values separated by ',' in one line
  • values separated by ' ' in one line
  • list of tagged values

jsonKeepNullsBuilder 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).trueRender attributes with NULL values to the REST call.
falseLeave out attributes with NULL values in the REST call (default).
jsonCompactBuilder 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.trueGenerate compact JSON (default).
falseGenerate pretty JSON.
userSpecify 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. e2e/e2e
Proxy Settings (if the called REST service is accessed via a proxy)
proxyTypeSpecify the proxy type.See CURLOPT_PROXYTYPE.
proxyURLSpecify the URL of the proxy server.See CURLOPT_PROXY.
proxyUserSpecify the proxy credentials.See CURLOPT_PROXYUSERPWD, valid format is <user>/<password>, e.g. e2e/e2e
SSL Settings (if the called REST service uses SSL)
sslCAInfoSpecify a file name containing additional certificates for the connection verification (e.g. additional root CAs).See CURLOPT_CAINFO.
sslCertificateFileSpecify a fle name containing the client certificate.See CURLOPT_SSLCERT.
sslCertificateTypeSpecify the type of the certificate.See CURLOPT_SSLCERTTYPE.
sslPrivateKeyFileSpecify a file name containing the private key.See CURLOPT_SSLKEY.
sslPrivateKeyPasswordSpecify the password for the private key.See CURLOPT_KEYPASSWD.
sslPrivateKeyTypeSpecify the type of the key.See CURLOPT_SSLKEYTYPE.
sslVerifyHostSpecify whether to verify the host information form the SSL connection.See CURLOPT_SSL_VERIFYHOST.
sslVerifyPeerSpecify 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.