REST Clients

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

REST Client

A REST client can be referenced by its name or by its universal 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 default and environments configurations.

REST Clients Tree Editor

Shows the REST clients and its environment configurations.

Add Client Adds a new REST client.
Add Environment Adds a new environment configuration for the selected REST client.
Remove Removes the selected environment or REST client configuration.

REST Client Details Editor

Shows the currently selected REST client or environment configuration.

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.
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()
```
Tip

To consume a REST service running in the same Axon.ivy Engine / Application as the client a set of Axon.ivy placeholders can be used. These placeholders are automatically resolved: {ivy.engine.host}, {ivy.engine.http.port}, {ivy.engine.context}, {ivy.request.application}.

E.g. http://{ivy.engine.host}:}{ivy.engine.http.port}/{ivy.engine.context}/api/{ivy.request.application}/my/service

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

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 Java Management Extensions (JMX). 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.