HTTP Endpoints

Comparable to: Express, Fastify, Flask

Key Concepts

Use the concepts below when they fit the task. Not every HTTP endpoint needs all of them.

• Each route is a registered function bound to a path and method via an HTTP trigger
• The handler receives an ApiRequest object containing

  body

  ,

  path_params

  ,

  headers

  , and

  method

• Handlers return

  { status_code, body, headers }

  to shape the HTTP response
• iii-http serves all registered routes on port 3111
• Path parameters use colon syntax (e.g.

  /users/:id

  ) and arrive in

  path_params

• Middleware can run before handlers via

  middleware_function_ids

  in the trigger config — see

  iii-http-middleware

  for details

Architecture

HTTP request
  → iii-http (port 3111)
    → registerTrigger route match (method + path)
      → registerFunction handler (receives ApiRequest)
        → { status_code, body, headers } response

iii Primitives and HTTP Trigger Config Used

registerFunction

registerTrigger({ type: 'http' })

config: { api_path: '/path', http_method: 'GET' }

config: { ..., middleware_function_ids: [...] }

Reference Implementation

See ../references/http-endpoints.js for the full working example — a REST API with parameterized routes handling GET and POST requests.

Also available in Python: ../references/http-endpoints.py

Also available in Rust: ../references/http-endpoints.rs

Common Patterns

Code using this pattern commonly includes, when relevant:

• registerWorker(url, { workerName })

  — worker initialization

• registerFunction(id, handler)

  — define the route handler

• registerTrigger({ type: 'http', config: { api_path, http_method } })

  — bind path and method

• req.body

  — parsed request body for POST/PUT

• req.path_params

  — extracted path parameters

• return { status_code: 200, body: { data }, headers: { 'Content-Type': 'application/json' } }

  — response shape

• const logger = new Logger()

  — structured logging per handler

Adapting This Pattern

Use the adaptations below when they apply to the task.

• Add more routes by registering additional functions and HTTP triggers with distinct paths or methods
• Use

  path_params

  for resource identifiers (e.g.

  /orders/:orderId

  )
• Return appropriate status codes (201 for creation, 404 for not found, 400 for bad input)
• For authenticated routes, use middleware (

  middleware_function_ids

  ) or inspect

  req.headers

  for tokens or API keys
• Chain work behind an endpoint by enqueuing to a queue after returning a 202 Accepted
• For reusable auth, logging, or rate-limiting before handlers, prefer

  iii-http-middleware

Pattern Boundaries

• If the task is about calling external HTTP APIs from iii functions, prefer

  iii-http-invoked-functions

  .
• If async processing is needed behind the endpoint, prefer

  iii-queue-processing

  for the background work.
• If the task is specifically about middleware chains (auth, logging, rate-limiting), prefer

  iii-http-middleware

  .
• Stay with

  iii-http-endpoints

  when iii owns the route and handles the inbound request directly.

When to Use

• Use this skill when the task is primarily about

  iii-http-endpoints

  in the iii engine.
• Triggers when the request directly asks for this pattern or an equivalent implementation.

Boundaries

• Never use this skill as a generic fallback for unrelated tasks.
• You must not apply this skill when a more specific iii skill is a better fit.
• Always verify environment and safety constraints before applying examples from this skill.