The AQ_RestServiceClient service makes it possible to call a REST webservice. Besides the functionality found in the old AQ_WebServiceClient this service introduces the possibility of connection overriding and inputting the URL parameter as an expression. 

Parameters

The following parameters can be set for the service from Studio:

Overriding parameters

In order to override parameters from configuration files one can use either the name of the AQ_RestServiceClient or the value given to the connectionOverride field. For better understanding the following picture is presented:

The overriding can be done in the application.properties file by either using the service name like this:

blueriq.connection.SendRest20.http.url=http://randomUrl:8080
blueriq.connection.SendRest20.http.username=randomUsername
blueriq.connection.SendRest20.http.password=randomPassword

... or by using the connection name like this:

blueriq.connection.connectionName.http.url=http://randomUrl:8080
blueriq.connection.connectionName.http.username=randomUsername
blueriq.connection.connectionName.http.password=randomPassword

Overriding using the service name VERSUS overriding using the connectionOverride

In order to illustrate the benefit of using the new connectionOverride parameter a simple example will be presented.

Say there is webservice with 5 operations: add, subtract, multiply, divide and modulo. For each operation there is a corresponding service call and for each of those service calls the url, username and password are overridden in the application.properties file using the service name. This means that even if the services call the same webservice (thus calling the same url with the same credentials) the override data must be specified for each of them. This is where the connectionOverride becomes useful by allowing each of those services to use a common connection name and eliminating the need of duplication.

Error handling

From Blueriq 11.10 and onward, any status code will be mapped to the profile. However, if the response body doesn't match the domain schema, the exception exit is taken. For empty response bodies, the status code is mapped to the profile as well.

Exit events

If no timeout occurs, the AQ_RestServiceClient throws the default event.

Authentication options

There are several authentication options, which are configurable per connection with properties:

No authentication

When no username and password are set for the service call (none is Studio and also non in the Connections Properties), then no authentication will be attempted. You should use this when the Rest Endpoint that you are calling is not secured.

Basic authentication

When a username and password are supplied, either in Studio or in the Connections Properties, these credentials will be supplied to the Rest Endpoint.

OpenID Connect authentication

See OpenID Connect for more information.

Oauth2 authentication

Available since Blueriq 13.12. When the Rest Endpoint that needs to be called is secured with OAuth2, you can set the property blueriq.connection.<connectionName>.http.authentication to oauth2. You need to fill out some extra properties that should be provided by the maintainer of the endpoint. See Connections Properties for those. Blueriq will request a token from the oauth2-token-endpoint and call the Rest Service with that token.

Since OAuth2 doesn't specify how certain properties are transmitted when requesting a token, we include a set of default behavior:

• When requesting a token, the grant_type and scope attributes will be sent in the request body, using the application/x-www-form-urlencoded encoding scheme.
• When requesting a token, the Client ID and the Client Secret will be sent as Basic Authentication.
• When requesting a token, the POST method is used.

• In the token response, we expect a JSON structure that at least contains an access_token and a token_type:

  {
    "access_token": "f608a968-b1ef-457a-8d1a-71ee007ac4d2",
    "token_type": "bearer"
  }

• Access tokens are not cached. Each Rest Service call will request a new token.

Customization

If you need different behavior, you can write your own custom Access Token Provider, that needs to implement the com.blueriq.component.api.oauth2.Oauth2AccessTokenProvider interface and you need to define is as a Spring Bean in your application.