HTTP

The HTTP Module exposes registered functions as HTTP endpoints.

modules::api::RestApiModule

Sample Configuration

- class: modules::api::RestApiModule
  config:
    port: 3111
    host: 0.0.0.0
    cors:
      allowed_origins:
        - http://localhost:3000
        - http://localhost:5173
      allowed_methods:
        - GET
        - POST
        - PUT
        - DELETE
        - OPTIONS

Configuration

number

The port to listen on. Defaults to 3111.

string

The host to listen on. Defaults to 0.0.0.0.

number

The default timeout in milliseconds for request processing. Defaults to 30000.

number

The maximum number of concurrent requests the server will handle. Defaults to 1024.

Cors

The CORS configuration.

Show Cors

string[]

required

The allowed origins.

string[]

required

The allowed methods.

number

Maximum request body size in bytes. Defaults to 1048576 (1 MB).

boolean

When true, the engine trusts proxy headers such as X-Forwarded-For for client IP resolution. Defaults to false.

string

Header name used to propagate or generate a request ID. Defaults to x-request-id.

boolean

When true, routes with and without a trailing slash are treated as equivalent. Defaults to false.

string

Function ID to invoke when no route matches a request. When unset, the engine returns a default 404 response.

Trigger Type

This module adds a new Trigger Type: http.

Show Trigger Config

string

required

The path of the API.

string

required

The HTTP method of the API.

string

Function ID for conditional execution. The engine invokes it with the request; if it returns false, the handler function is not called.

Sample code

const fn = iii.registerFunction({ id: 'api.getUsers' }, handler)
iii.registerTrigger({
  type: 'http',
  function_id: fn.id,
  config: {
    api_path: '/api/v1/users',
    http_method: 'GET',
  },
})

Request & Response Objects

ApiRequest

When an API trigger fires, the function receives an ApiRequest object:

string

The request path.

string

The HTTP method of the request (e.g., GET, POST).

Record<string, string>

Variables extracted from the URL path (e.g., /users/:id).

Record<string, string>

URL query string parameters.

any

The parsed request body (JSON).

Record<string, string>

HTTP request headers.

object

Metadata about the trigger that fired the function.

Show TriggerMetadata

string

The trigger type (e.g., http).

string

The matched route path pattern.

string

The HTTP method.

object

Request context object. Populated by middleware and available to handler functions.

ApiResponse

Functions must return an ApiResponse object:

number

HTTP status code (e.g., 200, 404, 500).

any

The response payload.

string[]

HTTP response headers as "Header-Name: value" strings (e.g., ["Content-Type: application/json"]). Optional.

Middleware

The HTTP module supports a middleware system that runs functions at defined phases of the request lifecycle. Middleware functions are registered using the http_middleware trigger type.

Phases

Phase	Description
`onRequest`	Runs before route matching.
`preHandler`	Runs after route match, before the handler.
`postHandler`	Runs after the handler returns a response.
`onResponse`	Runs after the response is sent (fire-and-forget).
`onError`	Runs when the handler returns an error.
`onTimeout`	Runs when the handler exceeds the configured timeout.

Phases execute in priority order (lower number = higher priority).

Middleware Trigger Config

Show Trigger Config

string

required

The lifecycle phase to attach to. One of: onRequest, preHandler, postHandler, onResponse, onError, onTimeout.

object

Limits the middleware to requests matching a path prefix. When omitted, applies to all routes.

Show Scope

string

required

Path prefix to match. Supports :param segments and a trailing * wildcard (e.g., /api/*).

number

Execution order within a phase. Lower values run first. Defaults to 0.

Middleware Function Contract

Middleware functions receive a MiddlewareRequest object:

string

The phase in which the middleware is executing.

object

The current ApiRequest object.

object

Accumulated context from previous middleware in the same phase.

object

Present on preHandler and later phases. Contains function_id and path_pattern.

object

Present on onResponse phase only. The response that was sent.

Middleware must return one of:

{ action: "continue", request?: object, context?: object } — pass control to the next middleware. Optional request and context patches are deep-merged into the current values.
{ action: "respond", response: { status_code, body, headers } } — short-circuit and return a response immediately. Subsequent middleware in the same phase is skipped.

Request Lifecycle

Example Handler

import { registerWorker } from 'iii-sdk'
import type { ApiRequest, ApiResponse } from 'iii-sdk'

const iii = registerWorker('ws://localhost:49134')

async function getUser(req: ApiRequest): Promise<ApiResponse> {
  const userId = req.path_params?.id
  const user = await database.findUser(userId)
  return {
    status_code: 200,
    body: { user },
    headers: { 'Content-Type': 'application/json' },
  }
}

const fn = iii.registerFunction({ id: 'api.getUser' }, getUser)
iii.registerTrigger({
  type: 'http',
  function_id: fn.id,
  config: {
    api_path: '/users/:id',
    http_method: 'GET',
  },
})

Getting Started

Primitives & Concepts

How-to Guides

Modules

Console

Advanced

Examples

Sample Configuration

Configuration

Trigger Type

Sample code

Request & Response Objects

ApiRequest

ApiResponse

Middleware

Phases

Middleware Trigger Config

Middleware Function Contract

Request Lifecycle

Example Handler

​Sample Configuration

​Configuration

​Trigger Type

​Sample code

​Request & Response Objects

​ApiRequest

​ApiResponse

​Middleware

​Phases

​Middleware Trigger Config

​Middleware Function Contract

​Request Lifecycle

​Example Handler

Sample Configuration

Configuration

Trigger Type

Sample code

Request & Response Objects

ApiRequest

ApiResponse

Middleware

Phases

Middleware Trigger Config

Middleware Function Contract

Request Lifecycle

Example Handler