restApi

Source processor for exposing REST endpoints. Can be built from an API specification or exposed as a generic endpoint.

By default, an error encountered by the REST endpoint is returned to the client and not processed further by the server. Such errors include malformed JSON or request bodies that don’t validate against the OpenAPI spec.

However, if the forwardMessagePreprocessingErrors option is enabled, these errors are captured by the flow-server and displayed in the Flow Traces page in Heartbeat. If forwardMessagePreprocessingErrors is also configured on the flow’s deadLetterStrategy, the error can be forwarded to a dead letter flow, just like errors occurring in the flow pipeline.

Properties

Name Summary

apiSpecId

ID of the API specification following the pattern <type>:<resourceId>:<revision>. Set <revision> to latest to retrieve the latest one. For example: OpenAPIv3:my-api-spec:latest. If apiSpecId is not set, a generic endpoint will be exposed instead.

validateResponse

Whether to configure validation of the REST API response. Response validation is turned off by default.

responseConversionCharacterSet

Optional character encoding to use if the response received after processing in the flow needs to be converted from binary format. Binary decoding defaults to UTF-8 unless otherwise specified here.

forwardMessagePreprocessingErrors

Whether to treat errors encountered at the rest endpoint as regular message processing errors. Example of such errors can be request parsing and validation failures.

When this feature is active (the default), these kinds of errors will be treated just like any other message processing error happening in the flow pipeline. I.e. they will be subject to regular error handing, and reported as failed messages in the monitoring tools. If the feature is deactivated the request will be rejected without any further processing.

This property is optional, and true by default.

name

Optional, descriptive name for the processor.

id

Required identifier of the processor, unique across all processors within the flow. Must be between 3 and 30 characters long; contain only lower and uppercase alphabetical characters (a-z and A-Z), numbers, dashes ("-"), and underscores ("_"); and start with an alphabetical character. In other words, it adheres to the regex pattern [a-zA-Z][a-zA-Z0-9_-]{2,29}.

exchangeProperties

Optional set of custom properties in a simple jdk-format, that are added to the message exchange properties before processing the incoming payload. Any existing properties with the same name will be replaced by properties defined here.

retainPayloadOnFailure

Whether the incoming payload is available for error processing on failure. Defaults to false.

Sub-builders

Name Summary

messageLoggingStrategy

Strategy for describing how a processor’s message is logged on the server.

payloadArchivingStrategy

Strategy for archiving payloads.

inboundTransformationStrategy

Strategy that customizes the conversion of an incoming payload by a processor (e.g., string to object). Should be used when the processor’s default conversion logic cannot be used.

Details

Endpoints

There are two ways to define a REST source:

  • Using a schema-based approach (requires passing an apiSpecId).

  • Using generic behavior (when an apiSpecId isn’t provided).

REST resources are exposed as endpoints under /{ownerId}/rs/{flowId}.

Both definition options support flow disablement through the management dashboard. Disabled flows will not process messages and will return a status of 503 (Service Unavailable) as long as they are disabled. Even though a flow is disabled, messages will still be pre-processed for validation.

Exchange Properties

There is a standard set of message exchange properties that will be associated with each message emitted from a REST source. These include the following:

Exchange Property Description

http.protocol

The protocol of the request (e.g., HTTP/1.1).

http.method

The HTTP request method (e.g., POST).

http.header

Prefix for request headers (e.g., A Content-Type header will be available as http.header.Content-Type).

http.query

Prefix for query parameters (e.g., A ?k1=v1 query string will be available as http.query.k1).

http.path

Prefix for path parameters. Values depend on which mode was used to create the REST source.

http.requestUri

Original URI that was used in the endpoint.

contentType

Shorthand property specifically for the Content-Type HTTP header.

inboundEntityByteSize

Entity size (in bytes), if the size is known. The size cannot be determined if chunked transfer encoding is used.
If there are duplicate headers or query parameters (e.g., ?k1=v1&k1=v2), both values will be available. A map processor, for instance, would have access to them in the #input.messageExchangeProperties array, where the corresponding array elements have the same name of http.query.k1.

The following exchange properties can also be set at any point in the flow to affect the response headers:

Exchange Property Description

httpResponseCode

The response status. Value must be an integer between 100 and 599. If this header is not set, a default value will be used. Otherwise, 500 will be returned and an error logged.

responseHeader.*

Properties prefixed with responseHeader will become custom HTTP headers. For example, a property named responseHeader.foobar with a value of baz would result in a response header of foobar: baz.

Schema-Based Model

This is the recommended approach to create REST sources. It exposes endpoints that are defined in an API specification. Currently, only the following schema type is supported:

Type File Extensions

OpenAPIv3

json, yml, yaml

The path for a specific operation is /{ownerId}/rs/{flowId}/{path from OpenAPI spec}. For example, if there is a defined path for /user, then it will be visible under /{ownerId}/rs/{flowId}/user. The selected operation will be used for both request and response validations.

In order to uniquely identify which endpoint was used, the http.operationId exchange property is added. If operationId is present in the OpenAPI spec, then that value is used. If not, the default generated value uses the pattern path_template-HTTPmethod. For example, the path template {param}/operation for a GET request will be translated to param_operation-GET.

A templated path is also used to generate the http.path exchange properties. For example, the path template {p1}/op/{p2} and request path v1/op/v2 would create the following properties:

Exchange Property Value

http.path.p1

v1

http.path.p2

v2

Schema-based endpoints have the following restrictions:

  • Only one content type is supported: application/json.

  • Only Basic and API key security schemes are supported. All non-supported schemes (e.g., Bearer) are removed when the source endpoint is created. If only non-supported schemes were provided, creation of the source endpoint will fail.

All non-2xx responses defined in the OpenAPI spec are not processed and will be used only for documentation purposes.

Generic Model

The generic model is designed to handle only basic cases where the default behavior is sufficient. There is no schema defined. Therefore, there is no input or output validation.

All HTTP operations are supported. Request entities are assumed to be JSON and are converted to the standard JSON compliant object model by default. If the request content type is set to application/x-www-form-urlencoded, the values are available as a list to accommodate possible duplicate keys. For example:

{
  "key1": ["value1", "value2"],
  "key2": ["value"]
}

If the request content type is set to any other non-JSON type, the entity is converted to a string.

By default, the response content type is set to application/json. The flow can override this by setting a response header for a different content type (e.g., responseHeader.Content-Type=application/xml;charset=UTF-8).

The path is divided into indexed segments. For example, the path one/two/three will be converted into the following exchange properties:

Exchange Property Value

http.path.1

one

http.path.2

two

http.path.3

three

It’s up to the flow developer to identity which endpoint was executed based on the http.* exchange properties.

Responses

Validation of the response is turned off by default.

If the REST source is configured with response validation, then the following apply:

  • Schema-based sources will validate the response code, headers, and body.

  • Generic sources will ignore the validation config.

The following algorithm is used to calculate the response status code:

  1. Use the value from the httpResponseCode exchange property.

  2. Find the first 2xx code defined in the OpenAPI spec, if schema-based.

  3. Use the default behavior:

    • 201 for POST operations.

    • 200 for all other operations.

Validation of the response when the response code is not defined in an OpenAPI spec will be done only when the default code is defined. In other cases, the response will be assumed to be correct.