Expose an HTTP Endpoint - Iii

Goal

Expose a Function as an HTTP endpoint so external clients can call it via REST.

Steps

1. Enable the REST API module

Make sure iii-config.yaml has the REST API module enabled:

yaml

  - class: modules::api::RestApiModule
    config:
      port: 3111
      host: localhost
      default_timeout: 30000
      concurrency_request_limit: 1024
      cors:
        allowed_origins:
          # To allow all origins, use '*':
          # - '*'
          - localhost
        allowed_methods:
          - GET
          - POST
          - PUT
          - DELETE
          - OPTIONS

2. Register the Function

<Tabs> <Tab title="Node / TypeScript"> ```typescript title="http-endpoint.ts" import {registerWorker, Logger} from 'iii-sdk'

const iii = registerWorker(process.env.III_URL ?? 'ws://localhost:49134')

iii.registerFunction({ id: 'users::create' }, async (req) => { const logger = new Logger() const { name, email } = req.body const user = { id: crypto.randomUUID(), name, email } logger.info('User created', { userId: user.id }) return { status_code: 201, body: user } })

</Tab>
<Tab title="Python">
```python title="http_endpoint.py"
import os
import uuid

from iii import Logger, register_worker

iii = register_worker(os.environ.get("III_URL", "ws://localhost:49134"))


def create_user(req):
    logger = Logger()
    name = req["body"]["name"]
    email = req["body"]["email"]
    user = {"id": str(uuid.uuid4()), "name": name, "email": email}
    logger.info("User created", {"userId": user["id"]})
    return {"status_code": 201, "body": user}


iii.register_function({"id": "users::create"}, create_user)

</Tab> <Tab title="Rust"> ```rust title="http_endpoint.rs" use iii_sdk::{register_worker, InitOptions, RegisterFunctionMessage, Logger}; use serde_json::json; use tokio::signal;

#[tokio::main] async fn main() -> Result<(), Box<dyn std::error::Error>> { let url = std::env::var("III_URL").unwrap_or_else(|_| "ws://127.0.0.1:49134".to_string()); let iii = register_worker(&url, InitOptions::default())?;

iii.register_function(
    RegisterFunctionMessage { id: "users::create".into(), description: None, request_format: None, response_format: None, metadata: None, invocation: None },
    |req| async move {
        let logger = Logger::new();
        let name = req["body"]["name"].as_str().unwrap_or("");
        let email = req["body"]["email"].as_str().unwrap_or("");
        let user_id = uuid::Uuid::new_v4().to_string();
        logger.info("User created", Some(json!({ "userId": user_id })));
        Ok(json!({
            "status_code": 201,
            "body": { "id": user_id, "name": name, "email": email }
        }))
    },
);

println!("HTTP endpoint ready on POST /users");
signal::ctrl_c().await?;

Ok(())

}

</Tab>
</Tabs>

### 3. Register the HTTP trigger

<Tabs>
<Tab title="Node / TypeScript">
```typescript title="http-trigger.ts"
iii.registerTrigger({
  type: 'http',
  function_id: 'users::create',
  config: { api_path: '/users', http_method: 'POST' },
})

</Tab> <Tab title="Python"> ```python title="http_trigger.py" iii.register_trigger({ "type": "http", "function_id": "users::create", "config": {"api_path": "/users", "http_method": "POST"}, }) ``` </Tab> <Tab title="Rust"> ```rust title="http_trigger.rs" iii.register_trigger(RegisterTriggerInput { trigger_type: "http".into(), function_id: "users::create".into(), config: json!({ "api_path": "/users", "http_method": "POST" }), })?; ``` </Tab> </Tabs>

4. Try it

bash

curl -X POST http://localhost:3111/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "[email protected]"}'

Result

Your Function is now accessible as POST /users on port 3111. The http trigger handles request parsing and response serialization automatically.

<Info title="Request and Response types"> HTTP-triggered Functions receive an `ApiRequest` and should return an `ApiResponse`. See the [SDK Reference](/api-reference/iii-sdk) for type details. </Info>