HTTP

Expose functions as HTTP endpoints.

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

port · number

The port to listen on. Defaults to 3111.

host · string

The host to listen on. Defaults to 0.0.0.0.

default_timeout · number

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

concurrency_request_limit · number

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

cors · Cors

The CORS configuration.

Show Cors

allowed_origins · string[] · required

The allowed origins.

allowed_methods · string[] · required

The allowed methods.

body_limit · number

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

trust_proxy · boolean

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

request_id_header · string

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

ignore_trailing_slash · boolean

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

not_found_function · 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

api_path · string · required

The path of the API.

http_method · string · required

The HTTP method of the API.

condition_function_id · string

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

middleware_function_ids · string[]

Function IDs for per-route middleware. The engine invokes each in order before the handler. Each must return { action: "continue" } or { action: "respond", response }.

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:

path · string

The request path.

method · string

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

path_params · Record<string, string>

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

query_params · Record<string, string>

URL query string parameters.

body · any

The parsed request body (JSON).

headers · Record<string, string>

HTTP request headers.

trigger · object

Metadata about the trigger that fired the function.

Show TriggerMetadata

type · string

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

path · string

The matched route path pattern.

method · string

The HTTP method.

context · object

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

ApiResponse

Functions must return an ApiResponse object:

status_code · number

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

body · any

The response payload.

headers · string[]

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

Middleware

The HTTP module supports middleware functions that run before the handler. There are two types:

• Per-route middleware — attached to a specific trigger via middleware_function_ids in trigger config
• Global middleware — configured in iii-config.yaml, runs on all HTTP routes

Global Middleware Configuration

middleware · MiddlewareConfig[]

List of global middleware functions. Each runs on every HTTP request, before conditions and per-route middleware.

Show MiddlewareConfig

function_id · string · required

Function ID of the middleware to invoke.

phase · string

Lifecycle phase. Currently only preHandler is supported. Defaults to preHandler.

priority · number

Execution order. Lower values run first. Defaults to 0.

- class: modules::api::RestApiModule
  config:
    port: 3111
    middleware:
      - function_id: "global::rate-limiter"
        phase: preHandler
        priority: 5
      - function_id: "global::auth"
        phase: preHandler
        priority: 10

Middleware Function Contract

Middleware functions receive a lightweight request object (no body):

phase · string

The phase in which the middleware is executing (preHandler).

request · object

Request metadata: path_params, query_params, headers, method. Does not include body.

context · object

Empty context object for future use.

Middleware must return one of:

• { action: "continue" } — proceed to the next middleware or handler.
• { action: "respond", response: { status_code, body, headers } } — short-circuit and return a response immediately. Remaining middleware and the handler are skipped.

Execution Order

1. Route match
2. Global middleware (from config, sorted by priority)
3. Condition check (if configured)
4. Per-route middleware (from trigger config, in order)
5. Body parsing
6. Handler function

See the HTTP Middleware how-to guide for full examples.

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',
  },
})