REST Clients

The REST clients configuration contains the definition of all REST services, which can be consumed from a BPM process.

Tip

Before you create a new REST Client you should have a look at the |axon-ivy| Market. You may find there already a connector.

REST Client

A REST client can be referenced by its name or by its universally unique identifier (UUID). The UUID is generated when a new REST client is created and will never change. The name of a REST client is given when a new REST client is created. It can be changed later. By referencing a REST client by its UUID ensures that renaming of the REST client will not break the reference.

Further information about how to use the REST clients can be found in the chapter REST Services.

Like other configurations a REST client can be configured differently per environment.

REST Client Editor

The REST client Editor allows to configure REST client configurations.

REST Clients Tree Editor

Shows the REST clients.

Add Client Adds a new REST client.
Remove Removes the selected REST client configuration.

REST Client Details Editor

Shows the currently selected REST client.

REST Client Section

UUID Universal unique identifier of the REST client. The REST client can be referenced by this UUID. Cannot be modified.
Name The name of the REST client. The REST client can be referenced by this name. Can be modified. Note that references using the name will break if you change it.
Icon Choose an icon that represents the system that this REST client communicates with. The icon will also be used as decorator icon on REST client call process elements that references this REST client.
Description Description of the REST client.
Uri The base URI under which the remote service publishes its resources (e.g. https://api.twitter.com/1.1).

The URI can contain template placeholders which are resolved later by the client user (e.g. https://api.twitter.com/{version}).
```
ivy.rest.client("twitter").resolveTemplate("version", "1.1").get()
```

OpenAPI Client Generator

The OpenAPI client generator wizard enables validation and inscription editor simplification features around concrete calls with a REST Client Activity. Click the Generate REST classes button to start the wizard.

../../_images/rest-client-editor-main-section.png

OpenAPI Clients

expose valid resource+method combos and their documentation
display and validate typed query and path parameters
are aware of the payload being to and fro and generates java objects for them

Pre-Requisites

In oder to generator an OpenAPI client you need an OpenAPI 3.0 JSON service descriptor.
The legacy Swagger 2.0 openapi.json format is also supported by the client generator.

../../_images/rest-client-generator-wizard.png

Migrate to OpenAPI

OpenAPI isn’t the only popular format to describe REST service capabilities.

You may need to integrate an OData service then you can convert your OData service description with our OData converter. The service description is usually available under the given service url ending with $metadata e.g. https://myService/cars/$metadata

If you have other types of service description then you may have a look at lucybot which is able to convert many other specifications to OpenAPI.

Authentication Section

HTTP Basic Adds support for HTTP Basic authentication.
HTTP Digest Adds support for HTTP Digest authentication.
NTLM Adds support for NTLM authentication. Optionally, the NTLM.domain and the NTLM.workstation can be configured in the properties section.
Username The name of the user used to authenticate the client.
Password The password of the user used to authenticate the client.

Features Section

JSON Adds a feature so that responses in JSON are mapped to Java objects and Java objects in requests are mapped to JSON.
Features List Shows the configured “features” classes. The classes configured here are registered in the WebTarget using the method register(Class). The classes need to implement a JAX-RS contract interface and must have a default constructor.
Add Adds a new feature class.
Remove Removes the selected feature.

Properties Section

Properties can customize the settings of the REST client or one of its features.

Add Adds a new property.
Add Password Adds a new password property. The value of a password property is not visible in the table and is stored encrypted in the configuration file.
Remove Removes the selected property.

Client properties

Well known properties of the client are documented here: org.glassfish.jersey.client.ClientProperties.

In order to configure SSL client authentication for a REST client call, you need to specify the property SSL.keyAlias. The value of this alias needs to correspond with a key alias available in the client keystore configured under SSL Client Settings.

JSON properties

The JSON feature knows many properties that customize the serialization from JSON to Java objects and vice versa.

It is for instance possible to read a very complex JSON object with many fields back to a Java object that contains only a subset of these fields. To allow this incomplete but efficient mapping the property Deserialization.FAIL_ON_UNKNOWN_PROPERTIES must be set to false.

Consult the Jackson documentation for a list of all configurable items:

Jackson Deserialization features can be set using Deserialization. as prefix. E.g. Deserialization.FAIL_ON_UNKNOWN_PROPERTIES
Jackson Serialization features can be set using Serialization. as prefix. E.g. Serialization.WRITE_ENUMS_USING_INDEX

Path properties

Properties prefixed with PATH. are used in resource paths on calling activities. So if your target resources contain templates like {api.version} which re-occur on each and every instance of a calling activity, you should set it as global path property on the RestClient, rather than re-declaring it on every instance of the calling element.

Example:

Given a valid resource of your remote service looks like this: https://api.twitter.com/{api.version}/status/...

Then the path template {api.version} can be set globally on the RestClient as property

Property	Value
PATH.api.version	2

The resolved uri would consequently look as follows: https://api.twitter.com/2/status/...

Connection properties

You can configure the library that is used to create and manage connections by setting a connection provider jersey.client.connectorProvider. By default Apache HTTP Client (org.glassfish.jersey.apache.connector.ApacheConnectorProvider) is used. This library uses a connection pool to reuse connections. The connection pool is limited to 5 connections by default. You can see how many connections are currently in use by using the live stats in the Engine Cockpit. If all connections are in use most of the time you should consider increasing the maximum connections of the pool to avoid performance issues. You can configure it by setting the property jersey.client.pool.maxConnections.

As an alternative to Apache HTTP Client you can use java.net.URLConnection from the Java core library (org.glassfish.jersey.client.HttpUrlConnectorProvider). This connection provider does not have a maximum connection limit but has other restrictions like no NTLM support.

Dynamic properties

You may need to adjust property values for multiple runtime environments. E.g. to call different service URIs for testing than in production, consequently with other credentials or OAUTH2 application identifiers.

You can forsee and simplify these configuration adjustments for operations by using Dynamic Configuration expressions in properties or any other configuration value. E.g. the property appId=${ivy.var.cloudAppId} will at runtime have the value of the variable called cloudAppId.