API

Note

Module name: Api

The API module lets Control expose HTTP endpoints for system-to-system integrations. Instead of starting a Forms flow in a browser, a caller can send an HTTP request directly to Control and let the request be processed by Pipes or proxied to another service.

Use the API module when you want to:

• expose a simple integration endpoint under Control's HTTP listener
• validate incoming requests with an authentication pipe
• run a request pipe and return its result directly
• proxy a request and response to another backend service

Runtime structure

At runtime, the Api module is configured in modules/api.json. The module defines a shared http_context and an array of endpoint definitions.

Each endpoint is registered as:

/<http_context>/<context_path>/<path>

context_path is optional. For every endpoint, Control also exposes a ping endpoint:

/<http_context>/<context_path>/<path>/ping

Endpoint processing

An API request is handled in the following order:

1. The request is routed to the endpoint path.
2. If the endpoint is not public, the auth.pipe is executed.
3. The request is handled by the configured request handler.
4. The response is built by the configured response handler.

The available handlers are:

• Pipes for pipe-based request or response processing
• DataProxy when the request or response should be proxied

DataProxy handler

DataProxy is used when Control should behave more like a thin HTTP proxy than a response renderer. The handler still calls a configured pipe, but it expects that pipe to return an HTTP-shaped result that can be forwarded back to the caller.

In practice, DataProxy is useful when the pipe calls another backend service and returns:

• status or status_code
• status_message
• headers
• body

The DataProxy response handler reads these fields and writes them directly to the outgoing HTTP response.

DataProxy compared to Pipes

Both handlers use Pipes internally, but they serve different purposes:

Handler	Typical use	How the request is built	How the response is built
Pipes	Integration endpoints where Control should interpret, enrich, or reshape data	Control can forward selected headers and parameters, populate request context, and optionally override session handling	Control renders the HTTP response itself by using response.type, response.template, and response.status
DataProxy	Proxy-style endpoints where another backend should decide the actual HTTP response	Control forwards the JSON request body as-is, or builds a small JSON object from request parameters	Control forwards the pipe result almost as-is by using returned status, headers, and body

Use Pipes when Control should own the integration logic and response format. Use DataProxy when the downstream service should effectively own the HTTP response and Control should mainly forward it.

Configuration in Control management

When API endpoints are managed through Control management, each endpoint is stored in its own directory:

config/modules/api_endpoints/<id>/
  endpoint.json
  pipes/

The endpoint configuration is stored in endpoint.json. Endpoint pipes are stored under pipes/ and are loaded by the shared Pipes module.

The management UI creates a technical endpoint id, a default auth pipe, and a default request pipe for each new endpoint.

Related documentation

• Properties
• Response template
• Pipes

In this section

• Properties
• Response template