Properties

Module properties

Name	Description	Default value	Mandatory
name	Must be Api.	N/A
http_context	Base HTTP context for all API endpoints.	/api
use_session	Enables platform sessions for API requests.	false
http_csrf.enabled	Enables CSRF protection for modifying requests such as PUT.	false
endpoints	Array of endpoint definitions.	N/A

Endpoint properties

Name	Description	Default value	Mandatory
path	Path segment used to register the endpoint. Legacy configurations may still use name, but path should be preferred.	N/A
context_path	Optional path segment inserted before path.	Empty
display_name	Display name shown in the management UI.	Uses path
description	Description shown in the management UI.	Uses path
public	If true, the endpoint is exposed without running the auth handler.	false
auth	Authentication settings used when public is not true.	N/A	Conditional
request	Defines how the incoming request is processed.	N/A
response	Defines how the outgoing response is produced.	N/A

Note

When public is false, auth.pipe must be configured.

Auth properties

Name	Description	Default value	Mandatory
auth.pipe	Pipe used to authenticate and enrich the request context.	N/A	Conditional
auth.headers	Which headers are forwarded to the auth pipe. Can be *, a single name, or a comma-separated list.	Empty
auth.params	Which request parameters are forwarded to the auth pipe. Can be *, a single name, or a comma-separated list.	Empty
auth.header_prefix	Optional prefix added when forwarded headers are mapped into the request context.	Empty
auth.param_prefix	Optional prefix added when forwarded parameters are mapped into the request context.	Empty

Request properties

Name	Description	Default value	Mandatory
request.handler	Request handler. Supported values in the UI are Pipes and DataProxy.	Pipes
request.pipe	Pipe executed for the request. With Pipes, this is the integration pipe that receives the prepared request context. With DataProxy, this is typically a proxy-oriented pipe that calls another service and returns HTTP-shaped data.	N/A
request.headers	Which headers are forwarded to the request pipe. Can be *, a single name, or a comma-separated list.	Empty
request.params	Which request parameters are forwarded to the request pipe. Can be *, a single name, or a comma-separated list.	Empty
request.header_prefix	Optional prefix added for forwarded headers.	Empty
request.param_prefix	Optional prefix added for forwarded parameters.	Empty
request.session_override	Lets the request use another session than the one identified by the current cookie.	false
request.session_id	Name of the request parameter that contains the replacement session id when request.session_override is enabled.	Empty	Conditional

Note

Header filtering, parameter filtering, prefixes, and session override are used together with the Pipes request handler. The DataProxy request handler is much thinner and mainly forwards the JSON request body as-is, or builds a small JSON object from request parameters.

Response properties

Name	Description	Default value	Mandatory
response.handler	Response handler. Supported values in the UI are DataProxy and Pipes.	Pipes
response.type	Content type returned when the response is built by the Pipes handler.	application/json
response.template	Template used to render the response body on a successful pipe result. If not set, the raw pipe response JSON is returned.	Empty
response.failure_template	Template used to render the response body when the pipe fails, if no per-reason template is set on the matching status entry. If not set, the response body is empty. See Response template for available scopes.	Empty
response.status	Array of status mappings. Each entry contains a regex, an HTTP status value, and an optional template. Entries are evaluated in order; the first match wins. Applied when the pipe fails.	Falls back to 400 when no mapping matches

Note

When response.handler is DataProxy, the pipe result is expected to contain HTTP response data such as status or status_code, status_message, headers, and body. The properties response.type, response.template, and response.status are used by the Pipes response handler, not by DataProxy.

Status mapping

response.status is used by the Pipes response handler to map a pipe failure reason to a specific HTTP status code and, optionally, a per-reason response template.

When it applies: status mappings are evaluated when the pipe throws a PipeFailureException or a PipeException (infrastructure error). If the pipe succeeds, the response is always 200. If the pipe throws any other exception, the response is always 500 regardless of status mappings.

What the regex matches against: the failure reason string returned by the pipe — the same value that appears in response.reason.

Matching rules:

• Each entry has a regex, an integer value, and an optional template.
• The regex is matched against the full reason string (Java full-string match — the pattern must cover the entire value, not just a substring).
• Entries are evaluated in config order; the first matching entry wins.
• If no pattern matches, or if no mappings are configured, the response status falls back to 400.

Template selection for failure responses:

1. If the matched entry has a template, that template is rendered.
2. Otherwise, response.failure_template is used if configured.
3. Otherwise, the response body is empty.

Example with per-reason templates:

"status": [
  { "regex": "validation_error", "value": 422, "template": "{\"type\":\"validation\",\"reason\":\"{{response.reason}}\"}" },
  { "regex": ".*ldap.*",         "value": 503, "template": "{\"type\":\"infra\",\"reason\":\"{{response.reason}}\"}" },
  { "regex": ".*",               "value": 400 }
]

A catch-all ".*" at the end is optional since 400 is already the default fallback. Use it only when you want to be explicit.

Handler comparison

Area	Pipes	DataProxy
Request processing	Builds a richer request object and can include forwarded headers, parameters, platform context, and session handling	Forwards the JSON request body as-is, or creates a small JSON payload from request parameters
Pipe output	Treated as integration data that Control interprets	Treated as HTTP response data that Control forwards
Response shaping	Control decides content type, body template, and status mapping	The downstream response decides status, headers, and body
Best fit	Controlled integration endpoints	Thin proxy or pass-through endpoints

Example

{
  "name": "Api",
  "config": {
    "http_context": "/api",
    "use_session": true,
    "endpoints": [
      {
        "path": "svc01",
        "display_name": "Service 01",
        "description": "Example API endpoint",
        "public": false,
        "auth": {
          "pipe": "svc01_auth_pipe",
          "headers": "*",
          "params": "token"
        },
        "request": {
          "handler": "Pipes",
          "pipe": "svc01_request_pipe",
          "headers": "host,x-trace-id",
          "params": "token,input",
          "session_override": true,
          "session_id": "token"
        },
        "response": {
          "handler": "Pipes",
          "type": "application/json",
          "template": "{\"result\":\"{{items.0.id}}\"}",
          "failure_template": "{\"error\":\"{{response.reason}}\"}",
          "status": [
            {
              "regex": "NOT_FOUND",
              "value": 404,
              "template": "{\"error\":\"not_found\"}"
            },
            {
              "regex": "UNAUTHORIZED.*",
              "value": 401
            }
          ]
        }
      }
    ]
  }
}

Operational notes

• Each endpoint also exposes a /ping path that returns a simple health response.
• If use_session is enabled, session and trace id can be reused across requests.
• Existing configurations may still use name instead of path. The management UI writes path.

Related

• Response template