# Properties

Documentation owner: product `control`; documentation version: `1.3.0`.
Source: `content/products/control/1.3.0/configuration-reference/modules/api/properties.md` at commit `eaf7a020437971baeee95e87eaf963636040ac71`.

## Module properties

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

## 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 | Yes |
| context_path | Optional path segment inserted before `path`. | Empty | No |
| display_name | Display name shown in the management UI. | Uses `path` | No |
| description | Description shown in the management UI. | Uses `path` | No |
| public | If `true`, the endpoint is exposed without running the auth handler. | `false` | No |
| auth | Authentication settings used when `public` is not `true`. | N/A | Yes |
| request | Defines how the incoming request is processed. | N/A | Yes |
| response | Defines how the outgoing response is produced. | N/A | Yes |

:::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 | Yes |
| auth.headers | Which headers are forwarded to the auth pipe. Can be `*`, a single name, or a comma-separated list. | Empty | No |
| auth.params | Which request parameters are forwarded to the auth pipe. Can be `*`, a single name, or a comma-separated list. | Empty | No |
| auth.header_prefix | Optional prefix added when forwarded headers are mapped into the request context. | Empty | No |
| auth.param_prefix | Optional prefix added when forwarded parameters are mapped into the request context. | Empty | No |

## Request properties

| Name | Description | Default value | Mandatory |
| --- | --- | --- | --- |
| request.handler | Request handler. Supported values in the UI are `Pipes` and `DataProxy`. | `Pipes` | No |
| 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 | Yes |
| request.headers | Which headers are forwarded to the request pipe. Can be `*`, a single name, or a comma-separated list. | Empty | No |
| request.params | Which request parameters are forwarded to the request pipe. Can be `*`, a single name, or a comma-separated list. | Empty | No |
| request.header_prefix | Optional prefix added for forwarded headers. | Empty | No |
| request.param_prefix | Optional prefix added for forwarded parameters. | Empty | No |
| request.session_override | Lets the request use another session than the one identified by the current cookie. | `false` | No |
| request.session_id | Name of the request parameter that contains the replacement session id when `request.session_override` is enabled. | Empty | Yes |

:::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` | No |
| response.type | Content type returned when the response is built by the `Pipes` handler. | `application/json` | No |
| 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 | No |
| 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](/products/control/configuration-reference/modules/api/response-template/) for available scopes. | Empty | No |
| 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 | No |

:::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:**

```json
"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

```json
{
  "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
            }
          ]
        }
      }
    ]
  }
}
```

<details>

<summary>Operational notes</summary>

* 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`.

</details>

## Related

* [Response template](/products/control/configuration-reference/modules/api/response-template/)