HTTP

Expose functions as HTTP endpoints with the http worker.

The http worker turns your functions into REST routes exposed as HTTP endpoints.

Before adding the worker

compose::add is served by a running Compose daemon. Keep the engine and a daemon for this project running in separate terminals before using any of the commands below. If this project does not have a Compose file yet, create worker-compose.yaml containing containers: {} first.

# terminal 1
iii --config config.yaml

# terminal 2, from the directory that contains worker-compose.yaml
iii compose --namespace dev --engine ws://127.0.0.1:49134

iii compose without a subcommand starts the Compose daemon. --namespace selects its namespace, and --engine connects it to the existing engine. These options are listed in the generated CLI reference.

Run the remaining commands from a third terminal in that same project directory:

iii trigger -n dev compose::add worker=http

This page covers the basic endpoint flow. For path patterns, methods, headers, and response handling, see the http worker docs. The worker’s server settings (port, host, CORS, timeouts) are managed at runtime through the configuration worker.

Create endpoints

The http worker exposes an http trigger type that binds a function to an HTTP method and path; the function then runs on every matching request. Here is the full path from a running engine to a live endpoint.

registerTrigger is deprecated in 0.25, but the http worker still publishes the http trigger type, so it remains the way to create endpoints. It logs one warning per process. See Providers not migrated yet.

1. In a worker, register the function you want to expose and bind an http trigger to it. If you do not have a worker yet, follow Create a new worker, then edit its source. The handler receives the request (body, headers, method) and its return value becomes the response:

Node / TypeScript

import { registerWorker } from "iii-sdk";

const url = process.env.III_URL;
if (!url) throw new Error("III_URL must be set");
const worker = registerWorker(url, {
  workerName: "my-worker",
  namespace: "orders",
});

worker.registerFunction("http::add", async (payload: { body: { a: number; b: number } }) => ({
  status_code: 200,
  body: { c: payload.body.a + payload.body.b },
  headers: { "Content-Type": "application/json" },
}));

worker.registerTrigger({
  type: "http",
  function_id: "http::add",
  config: { api_path: "/math/add", http_method: "POST" },
});

Python

import os
from iii import register_worker, InitOptions

worker = register_worker(
    os.environ["III_URL"],
    InitOptions(worker_name="my-worker", namespace="orders"),
)

def add(payload: dict) -> dict:
    body = payload["body"]
    return {
        "status_code": 200,
        "body": {"c": body["a"] + body["b"]},
        "headers": {"Content-Type": "application/json"},
    }

worker.register_function("http::add", add)

worker.register_trigger({
    "type": "http",
    "function_id": "http::add",
    "config": {"api_path": "/math/add", "http_method": "POST"},
})

Rust

use iii_sdk::builtin_triggers::{HttpMethod, HttpTriggerConfig};
use iii_sdk::runtime::WorkerMetadata;
use iii_sdk::trigger::IIITrigger;
use iii_sdk::{InitOptions, RegisterFunction, register_worker};
use schemars::JsonSchema;
use serde::Deserialize;
use serde_json::json;

#[derive(Deserialize, JsonSchema)]
struct AddRequest {
    body: AddBody,
}
#[derive(Deserialize, JsonSchema)]
struct AddBody {
    a: i64,
    b: i64,
}

let url = std::env::var("III_URL").expect("III_URL must be set");
let worker = register_worker(
    &url,
    InitOptions {
        metadata: Some(WorkerMetadata {
            name: "my-worker".into(),
            ..Default::default()
        }),
        namespace: Some("orders".into()),
        ..Default::default()
    },
);

worker.register_function(
    "http::add",
    RegisterFunction::new(|req: AddRequest| {
        Ok(json!({
            "status_code": 200,
            "body": { "c": req.body.a + req.body.b },
            "headers": { "Content-Type": "application/json" }
        }))
    }),
);

worker.register_trigger(
    IIITrigger::Http(HttpTriggerConfig::new("/math/add").method(HttpMethod::Post))
        .for_function("http::add"),
)?;

The Rust SDK sets the worker name through InitOptions.metadata.name; Node uses workerName, and Python uses worker_name. All three examples register the name my-worker.

2. Add the worker to Compose, pointing at its directory:

iii trigger -n dev compose::add worker=./my-worker

For path patterns, request and response shapes, and the other configuration options, see the http worker docs.

Calling the endpoint

Once the trigger is registered, set HTTP_WORKER_URL to the address configured for the http worker and call the endpoint:

# call the exposed function
curl -X POST "$HTTP_WORKER_URL/math/add" -H 'content-type: application/json' -d '{"a":2,"b":3}'