REST Listener

REST Listener

A REST listener consumes a HTTP-REST request and offers its content as a ConnectMessage.

This listener is a request/response consumer, which means that a response must be returned. In addition this consumer can handle REST URL type requests.

This can happen through a host:port/context-path/ combination. For every combination, a separate server context is started. 
Listeners with the same host:port/context combination will use the same server context. The HTTP server will be generated and configured automatically.

When a Message reply component is configured at the end of the flow, the result from the service is sent back to the HTTP invoker.

Also, thrown exceptions will be sent back to the HTTP invoker, instead of being caught by the connect exception handling mechanism.

REST Patterns

REST patterns grants the user more fine-grained control over endpoint mapping as well as allow the user to map path and query variables to ConnectMessage properties. We offer two styles of REST patterns,

  • Legacy style REST patterns (Default)
  • OpenAPI style REST patterns

Legacy REST patterns are the default syntax. If you want to use the new OpenAPI style REST patterns, you will need to enable the REST Pattern As OpenAPI option. Note that both styles require you to prepend the context path to the REST pattern.

Example Legacy Style Rest Pattern

An example of a legacy style REST pattern is /context/path/[user]/{}/order?[id]={}. In this example we use "[user]/{}" to map the path element after "user" to the ConnectMessage property "user" and [id]={} to map the query parameter "id" to the ConnectMessage property "id". So if a request is made with the request URL /context/path/user/john/order?id=42, the resulting ConnectMessage will have properties "user" and "id" with values "john" and "42" respectively.

Example OpenAPI Style Rest Pattern

An equivalent example of an OpenAPI style REST pattern is /context/path/user/{user}/order.

If you use query variables in your URL then the OpenAPI style option requires you to specify the query variables you want to map in a separate attribute mapped-query-params (only visible if OpenAPI is enabled).

So assuming we've set this attribute to the value "id" and a request is made with the request URL /context/path/user/john/order?id=42, the resulting ConnectMessage will have properties "user" and "id" with values "john" and "42" respectively.

Please note that OpenAPI style REST patterns are preferred over legacy style REST patterns because of clearer syntax and being slightly more expressive.

In both styles it is possible to add wildcards to the patterns, for example we can have the OpenAPI style pattern /context/path/user/*/{order}/*/date. The "*" elements will match exactly one path element.

Finally, there is also the option to match on more than one path element. For example, /context/path/user/** or /context/path/user/{*details}. The difference between ** and {*variableName} is that in the latter the matching elements are mapped to a property of the outgoing ConnectMessage. Note that "**" and "{*variableName}" may only occur at the end of a pattern, e.g. /context/path/**/user is not valid.

OAuth2/OIDC Security

The REST Listener supports security through OAuth 2.0 or OpenID Connect (OIDC). The setup requires either an issuer URI or a JSON Web Key Set (JWKS) URI. In the case of an issuer URI, the REST Listener will use this URI to look up the metadata of the authorization server. This requires that the authorization server is either an OIDC server or implements an OAuth2 metadata endpoint as outlined in RFC8414, section 3.

For example, suppose we are using an OIDC server with issuer URI, www.example.com/issuer. The REST listener will configure the OIDC security using the info found at [www.example.com/issuer/.well-known/openid-configuration](http://www.example.com/issuer/.well-known/openid-configuration). The suffix .well-known/openid-configuration is a convention from the OIDC specification.

JWT Claim Expression

The JSON Web Token (JWT) claim expression can be used to either allow or deny requests based on the claims inside a JWT token.

A JWT is a base64-encoded structure consisting of three parts; a header, a payload and a signature. The payload is a JSON object containing a number of key/value pairs called "claims". These claims are added by the OAuth2/OIDC server and might have domain specific information. One can examine JWTs using the site https://jwt.io/.

The JWT claim expression can assert if claims should or should not be present in an access token. For example, given the following claim section in a JWT:

{
 "string-claim": "string-value",
 "boolean-claim": true,
 "number-claim": 42
 "array-claim": ["value1", "value2"],
 "object-claim": {"name": "foobar", "value": [{"nested-value": 42}, {"another-bool": false}]}
}

First note that the claim section is a JSON object, and the values of its claims can in turn be JSON objects, arrays, strings, numbers or booleans.

Now consider the following example scenarios:

(1) We only accept a JWT if the string-claim has value string-value: The JWT claim expression would be '"string-claim"."string-value"'. Note the usage of single and double quotes.

(2) We only accept a JWT if the string-claim does have value string-value. The corresponding JWT claim expression would be ['not', '"string-claim"."string-value"'].

(3) We only accept a JWT if the boolean-claim has value true and the number-claim has value 42. The corresponding JWT claim expression would be ['and', '"boolean-claim".true', '"number-claim".42'].

(4) We only accept a JWT if the array-claim contains value value2 or if the object-claim has a field name with value foobar, or if the boolean-claim has value false. The corresponding JWT claim expression would be ['or', '"array-claim"."value2"', '"object-claim"."name"."foobar"', '"boolean-claim".false'].

(5) Finally, here is an example of how to nest multiple operators to create a composite JWT claim expression, ['and', '"string-claim"."string-value"', ['or', '"object-claim"."value"."nested-value".42', '"array-claim"."value1"'], ['not', '"non-existent-claim"."foobar"']].

So, there are three operators, and, or and not. and and or can have two or more arguments. not always has one argument. Claim values are defined via '<claim-name>.<value1>.<value2>.etc' syntax.

 

In the table below, you will find an explanation of these properties. All attributes with a ‘*’ are mandatory.

Attribute

Description

Name*

By default, we fill this out with the technical ‘tag’, followed by a serial number. Changing the name is optional.

Enabled

Set this value to true, if you want this consumer to be enabled.

Consumer Autostart

Consumer will be started at startup of the interface

Hostname

Hostname used to create the endpoint

Port

Port number. The default is the Jetty port.

Context Path

Path on which to open webservice endpoint. A custom Context Path should always start with a forward slash (/). So for instance: "/CustomPath".

Method

Specify which HTTP Methods are allowed (GET/POST/HEAD/OPTIONS/PUT/PATCH/DELETE/TRACE). You may also use a comma separated list.

Input can be done by clicking in the lower part of the box. A drop-down menu will appear and you can select, or type your selection:

MessagePartName

Name of the MessagePart in a ConnectMessage where the content of the file is being stored.

Response Timeout

Time in milliseconds to wait before time-out.

Mapped Request Headers

A comma separated list of headers to be mapped from HTTP request to the ConnectMessage

Mapped Response Headers

A comma separated list of headers to be mapped from the ConnectMessage to the HTTP response

Non-Standard HTTP Header Prefix

Specify the prefix for the transfer of non-standard HTTP headers. Defaults to blank.

Expected Content Type

Specify which content-type may be expected to be correctly mapped to a useable format. This will override default content-type mapping.

Use Form/Multipart Mapping

This will enable mapping payloads with Content-Type application/x-www-form-urlencoded and multipart/form-data to multiple ConnectMessageParts.

Form/Multipart Key Header Name

When using the form/multipart mapping each ConnectMessagePart gets a header with the value of the original key. This setting determines the name of that header.

Form/Multipart Mapping Type

Determines the manner in which the name of the ConnectMessageParts are generated when using form/multipart mapping.

Form/Multipart Mapping Prefix

Only available if Use Form URL Encoded Mapping Type is set to USE_PREFIX_POSTFIX.

Use this prefix when generating the ConnectMessagePart name.

Form/Multipart Mapping Postfix

Only available if Use Form URL Encoded Mapping Type is set to USE_PREFIX_POSTFIX.

Use this postfix when generating the ConnectMessagePart name.

Enable TLS

Enables TLS Connector. When set to true, the keystore value and alias value should be set. Otherwise the defaults will be used.

Certificate alias in Keystore

 

This attribute is only visible when the attribute Enable TLS has value true.

Set the certificate alias for the selected server certificate. Should exist in defined keystore.

Key password

 

This attribute is only visible when advanced mode is enabled and the attribute Enable TLS has value true.

Password for the certificate key. If left empty the default key password will be used.

Keystore location

 

This attribute is only visible when advanced mode is enabled and the attribute Enable TLS has value true.

The location of the keystore. Should be a path to the keystore JKS file. If left empty the default keystore will be used.

Keystore password

 

This attribute is only visible when advanced mode is enabled and the attribute Enable TLS has value true.

Password of the keystore. If left empty the default keystore password will be used.

Authentication Realm

Provide an Authentication file from Resources to specify configured Authentication for selected Scheme. See chapter on Providing Authentication for HTTP/WS Listeners. For more information, follow this link.

Authentication Scheme

Select desired Authentication Schema (NONE, BASIC, JDBC, LDAP, OAUTH2_OIDC_ISSUER_URI, OAUTH2_OIDC_JWK_SET_URI). See chapter on Providing Authentication for HTTP/WS Listeners and the section on OAuth2/OIDC security on this page. For more information, follow this link.

Issuer URI

If Authentication Scheme is set to OAUTH2_OIDC_ISSUER_URI, you are required to provide an OAuth2/OIDC issuer url. See the section above on OAuth2/OIDC Security.

JWK Set URI

If Authentication Scheme is set to OAUTH2_OIDC_JWK_SET_URI, you are required to provide a JSON Web Key (JWK) Set URI. See the section above on OAuth2/OIDC Security.

OAuth2/OIDC Scope

If Authentication Scheme is set to OAuth2/OIDC, you can optionally specify that access tokens are required to have a certain scope. In the case of JWTs this is a scope included in the scopes claim. Note that you can currently only specify a single scope. If left empty, no further requirements are imposed on access tokens.

JWT Claim Expression

Only available if Authentication Scheme is set to OAuth2/OIDC.

The JSON Web Token (JWT) claim expression can be used to allow or deny requests based on the claims inside the access token (provided it is a JWT) used by OAuth2/OIDC. See the documentation above for more information.

REST Pattern

Provide used REST Pattern for this request. For example /contextPath/[customerId]/{}/[email]/{}  Every Pattern must start with the Context Path. Every parameter will be stored as a ConnectMessage Property on the ConnectMessage.  See the above section on REST patterns for more information.

REST Parameters As XML

Setting this to true will add a separate messagepart with id 'restXml' containing all the REST parameters and values in XML format.

REST Pattern As OpenAPI

Enable to use OpenAPI standard of REST Patterns (like /object/{parameter}). Default is false (like /object/[parameter]/{}).

Mapped Query Parameters

This attribute is only visible when the attribute REST Pattern as OpenAPI has value true.

A comma separated list of query parameters to be mapped from the request URL to the ConnectMessage

Enable CORS

Should Cross-Origin Resource Sharing be enabled? Note that by enabling CORS all origins and all methods are allowed. It is currently not possible to explicitly specify which origins, methods, headers etc. are allowed. Furthermore, note that you should explicitly add the OPTIONS method if you want to support CORS preflight requests.

REST Listener Properties Filename

This attribute is only visible when advanced mode is enabled.

The name of the Java properties file containing additional config for the REST Listener.

Description

Description of the specific consumer. This is for documentation purposes.

Enable CORS

When you enable CORS, you need to add some extra information. This will look like this:

Attribute Description
CORS Allowed Origins A comma separated list of origins that are allowed to access this resource. The special value '*' allows all origins.
CORS Allowed Methods A list of HTTP methods that are allowed to access this resource. The special value '*' allows all methods.
CORS Allowed Headers A comma separated list of HTTP headers that are allowed to be used by the client. The special value '*' allows all headers.
CORS Exposed Headers A comma separated list of HTTP headers that are allowed to be exposed to the client. Note that this attribute does not support the special value '*'.
CORS Allow Credentials Whether user credentials are allowed to be sent.

CORS Max Age in Seconds

The name of the Java properties file containing additional config for the REST Listener.

 

Enable TLS

When you enable TLS, you need to add some extra information. This will look like this:

Attribute

Description

Certificate Alias in Keystore

Set the certificate alias for the selected server certificate. Should exist in defined keystore.

Key Password

Password of the keystore. If left empty the default keystore password will be used..

Keystore Location

The location of the keystore. Should be a path to the keystore JKS file. If left empty the default keystore will be used.

Keystore Password

Password of the keystore. If left empty the default keystore password will be used.

Expected content type

It is possible that if you use STRING as an expected content type, you will see the following message in your log file.

org.springframework.messaging.MessagingException: Could not convert reply: no suitable HttpMessageConverter found for type [java.lang.String] and accept types [[application/thisisacontenttype]]

If this is the case, you should try to use de DEFAULT setting for the expected content type. Most of the time the message will disappear.