REST Clients

The REST clients configuration contains the definition of all REST services, to be consumed by an Axon Ivy process.

Tip

Before you create a new REST client, take a look at the Axon Ivy Market. There, you may find a suitable connector already.

REST Client

A REST client can be referenced by name or universally unique identifier (UUID). Axon Ivy generates the UUID when a new REST client is created and will never change. You define the name of a REST client when you create a new REST client. You can change it later. To ensure that renaming a REST client will not break the reference, refer to the REST client by its UUID only.

Find additional information on using REST clients in the chapter REST Services.

REST Client Editor

Use the REST client Editor to create and edit REST client configurations.

The left side of the REST editor contains all the clients. A click on one of the clients will show the properties of the selected client on the right side of the editor.

Press to add a new REST client.
Press to delete the selected REST client.

REST Client Details Editor

Shows the details of the currently selected REST client.

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. You can refer to the REST client by this name. You can modify it. 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. Axon Ivy uses this icon as a decorator icon on REST client call process elements that reference 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()
```

Authentication Section

HTTP Basic Adds support for HTTP Basic authentication.
HTTP Digest Adds support for HTTP Digest authentication.
NTLM Adds support for NTLM (Windows) authentication. Optionally, you can configure the NTLM.domain and the NTLM.workstation in the properties section. This feature is deprecated and will be removed in a future version. Microsoft recommends using more modern and secure authentication methods such as Basic or Digest Authentication combined with TLS.
Username The name of the user used to authenticate the client with the service.
Password The password of the user used to authenticate the client with the service.

Features Section

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 javax.ws.rs.core.Feature and must have a default constructor.

Tip

E.g. add the JsonFeature that maps Java objects to JSON for requests and JSON to Java objects for responses.

Properties Section

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

Tip

Change a property to a password to hide its value in the configuration and store it encrypted. This is especially useful for properties that contain sensitive information like credentials.

Client Properties

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

To configure SSL client authentication for a REST client call, 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 Settings.

JSON Properties

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

It is 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 a prefix. E.g., Deserialization.FAIL_ON_UNKNOWN_PROPERTIES
Jackson Serialization features can be set using Serialization. as a prefix. E.g., Serialization.WRITE_ENUMS_USING_INDEX

Path Properties

Properties can be defined as Path Properties. Those are used in resource paths on calling activities. If your target resources contain templates like {api.version} which re-occur on every instance of a call activity, you should set it as a global path property in the REST Client, rather than re-declaring it on every instance of the calling element.

Hint

Example:

If 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 REST Client as a property:

Type	Property	Value
Path	api.version	2

The resolved URI would consequently be: https://api.twitter.com/2/status/...

Connection Properties

You can configure the library used to create and manage connections by setting a connector provider jersey.client.connectorProvider. By default, the Apache HTTP Client (org.glassfish.jersey.apache5.connector.Apache5ConnectorProvider) is used. This library uses a connection pool to reuse connections. By default, the connection pool is limited to 5 connections. You can see how many connections are currently in use by looking at the life stats in the Engine Cockpit. If all connections are in use most of the time, consider increasing the maximum number of connections in the pool to avoid performance issues. Configure it by setting the property jersey.client.pool.maxConnections.

As an alternative to the 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 missing NTLM support.

Dynamic Properties

You may need to adjust property values for multiple runtime environments. E.g., you call different service URIs for test and production, consequently with different credentials or OAUTH2 application identifiers.

If you anticipate this need, then you can simplify these configuration adjustments for operations by using Dynamic Configuration expressions in both properties and other configuration values. E.g., the property appId=${ivy.var.cloudAppId} is evaluated at runtime and has the value of the variable called cloudAppId. Thus, your database name is now configurable using variable cloudAppId. Operations need to set this variable correctly; they do not need to dive into the configuration of this external database.

OpenAPI Client Generator

The OpenAPI client generator wizard provides validation and inscription editor simplification features for specific calls with a REST Client Activity. Press to open the OpenAPI client generator wizard.

OpenAPI Clients

expose valid resource+method combos and their documentation
display and validate typed query- and path parameters
are aware of the payloads sent to and fro and generate Java objects for them

Pre-Requisites

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

Migrate to OpenAPI

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

If you need to integrate an OData service, 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 descriptions, you may have a look at lucybot. It is able to convert many other specification types to OpenAPI.