Skip to main content

​
Quickstart Guide

This guide walks you through creating your first iii function and exposing it via HTTP. You’ll have a working API endpoint in under 5 minutes.

​
Prerequisites

  • iii engine installed (installation guide)
  • Node.js, Python, or Rust development environment
  • Terminal/command line access

​
Step 1: Start the Engine

First, start the iii engine on your local machine: 
iii
You should see output indicating the engine has started: 
2024-03-03T10:00:00.123Z  INFO iii: Starting iii engine v0.7.0
2024-03-03T10:00:00.124Z  INFO iii: WebSocket server listening on 127.0.0.1:49134
2024-03-03T10:00:00.125Z  INFO iii: HTTP API listening on 127.0.0.1:3111
The engine runs on two main ports:
  • 49134: WebSocket for worker connections
  • 3111: HTTP API for triggering functions

​
Step 2: Install the SDK

Choose your preferred language and install the corresponding SDK: 
npm install iii-sdk

​
Step 3: Create Your First Function

Now create a simple greeting function that responds via HTTP. 
import { init } from 'iii-sdk';

// Connect to the engine
const iii = init('ws://localhost:49134');

// Register a greeting function
iii.registerFunction(
  { id: 'greet.hello' },
  async (input) => {
    const name = input.name || 'World';
    return {
      message: `Hello, ${name}!`,
      timestamp: new Date().toISOString()
    };
  }
);

// Expose it via HTTP POST /greet
iii.registerTrigger({
  type: 'http',
  function_id: 'greet.hello',
  config: {
    api_path: 'greet',
    http_method: 'POST'
  }
});

console.log('Function registered! Try:');
console.log('curl -X POST http://localhost:3111/greet -H "Content-Type: application/json" -d \'{"name":"Alice"}\' ');

​
Step 4: Run Your Worker

Execute your worker application: 
node app.js
You should see confirmation that your function is registered and ready.

​
Step 5: Test Your Function

Now test your function by calling the HTTP endpoint: 
curl -X POST http://localhost:3111/greet \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice"}'
Expected response: 
{
  "message": "Hello, Alice!",
  "timestamp": "2024-03-03T10:05:30.123Z"
}
The function is automatically discovered and routed by the iii engine. No configuration files or manual registration required!

​
Understanding What Happened

Let’s break down what you just built:
1

Engine Started

The iii engine started and began listening for worker connections on port 49134 and HTTP requests on port 3111.
2

Worker Connected

Your worker application connected to the engine via WebSocket at ws://localhost:49134.
3

Function Registered

The greet.hello function was registered with the engine using the registerFunction SDK method.
4

Trigger Created

An HTTP trigger was created that maps POST /greet to the greet.hello function.
5

Request Routed

When you called the endpoint, the engine:
  1. Received the HTTP POST request
  2. Routed it to the registered worker
  3. Invoked the greet.hello function with the JSON payload
  4. Returned the function’s response as the HTTP response

​
Next: Add More Functionality

Now that you have a working function, let’s add more capabilities.

​
Add a Queue Trigger

Process messages asynchronously from a queue: 
// Register a job processing function
iii.registerFunction(
  { id: 'jobs.process' },
  async (input) => {
    console.log('Processing job:', input);
    // Do work here
    return { status: 'completed', jobId: input.id };
  }
);

// Subscribe to queue topic
iii.registerTrigger({
  type: 'queue',
  function_id: 'jobs.process',
  config: {
    topic: 'jobs.incoming'
  }
});

// Emit a job to the queue
iii.call('queue.emit', {
  topic: 'jobs.incoming',
  data: { id: '123', task: 'send_email' }
});
Queue triggers require Redis. Make sure Redis is running at redis://localhost:6379 or configure a different URL in your config.

​
Add a Cron Trigger

Schedule a function to run periodically: 
// Register a scheduled task
iii.registerFunction(
  { id: 'tasks.cleanup' },
  async () => {
    console.log('Running cleanup task...');
    // Cleanup logic here
    return { cleaned: true };
  }
);

// Run every 5 minutes
iii.registerTrigger({
  type: 'cron',
  function_id: 'tasks.cleanup',
  config: {
    schedule: '*/5 * * * *'  // cron syntax
  }
});

​
Common Patterns

​
Invoke Functions from Other Functions

Functions can call each other: 
// Call another function
const result = await iii.call('math.add', { a: 5, b: 3 });
console.log(result); // { sum: 8 }

​
Use Path Parameters

Extract values from URL paths: 
iii.registerTrigger({
  type: 'http',
  function_id: 'users.get',
  config: {
    api_path: 'users/:id',  // :id becomes a parameter
    http_method: 'GET'
  }
});

// Access in function:
iii.registerFunction({ id: 'users.get' }, async (input) => {
  const userId = input.id;  // from path parameter
  return { userId, name: 'Alice' };
});

​
Handle Multiple HTTP Methods

Register different triggers for the same function: 
iii.registerTrigger({
  type: 'http',
  function_id: 'items.list',
  config: { api_path: 'items', http_method: 'GET' }
});

iii.registerTrigger({
  type: 'http',
  function_id: 'items.create',
  config: { api_path: 'items', http_method: 'POST' }
});

​
Troubleshooting

  • Ensure the engine is running (iii command)
  • Verify the WebSocket URL is correct: ws://localhost:49134
  • Check firewall settings aren’t blocking port 49134
  • Confirm the trigger was registered successfully
  • Check the api_path matches your request URL
  • Verify the worker is still connected (check engine logs)
  • These modules require Redis running at redis://localhost:6379
  • Start Redis: docker run -p 6379:6379 redis:7-alpine
  • Or configure a different Redis URL in config.yaml
  • Check worker console for error messages
  • Enable debug logging: RUST_LOG=debug iii
  • Functions should return errors in the format: { error: { code: 'ERR_CODE', message: 'Description' } }

​
What’s Next?

Core Concepts

Learn about Functions, Triggers, and Discovery in depth

Explore Modules

Discover all available modules: HTTP, Queue, Cron, Stream, State

SDK Reference

Dive into SDK documentation for your language

Deploy to Production

Learn best practices for production deployments
Pro tip: Use environment variables in your config for different environments. See the Configuration guide for details.

Build docs developers (and LLMs) love

Get started for freeTalk to us