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 Client Editor

Rest Client Editor

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: