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, i.e. legacy style REST patterns and 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.

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.

An equivalent example of an OpenAPI style REST pattern is /context/path/user/{user}/order. 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.

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:

MessagePart

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.

Enable SSL

Enables SSL Connector. When set to true, the keystore value and alias value should be set. Otherwise the defaults 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.

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]/{}).

Description

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

 

Enable SSL

When you enable SSL, 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 certificate. Should exist in defined keystore. Defaults to the internal self-signed certificate.

Key Password

Password for the certificate key. (Defaults to internal Keystore)

Keystore Location

The location of the keystore. Should be a path to the keystore JKS file. (Defaults to internal Keystore)

Keystore Password

Password of the keystore. (Defaults to internal Keystore)