API development: .api.iwc

Purpose: an HTTP endpoint under /api, with a request contract (what it accepts), a response contract (what it returns), security, and exactly one implementation: a built-in operation, an action, or a workflow transition. When: for every form submission, every data source that isn't a direct table read, and anything a mobile app or another system calls.

Structure

{
  "name": "products",
  "method": "GET",
  "path": "/products",
  "description": "The public catalogue.",
  "operation": "db.list",
  "resource": "product.schema.iwc",
  "request": {
    "query": {
      "category": { "type": "string" },
      "sort": { "type": "string", "enum": ["name", "price", "-price"] },
      "q": { "type": "string", "maxLength": 60 },
      "page": { "type": "integer", "min": 1 },
      "limit": { "type": "integer", "min": 1, "max": 100 }
    }
  },
  "response": { "type": "list", "fields": { "id": "string", "name": "string", "price": "number", "image": "string" } },
  "security": { "auth": false, "rateLimit": "120/1m" },
  "cache": "30s"
}

Implementations

Built-in operations

Every db.* operation applies the schema's access rules, so db.update on an owner-only table can only touch the caller's rows. Someone else's row looks exactly like a missing one (404), so ids can't be probed.

An action

{
  "name": "checkout",
  "method": "POST",
  "path": "/checkout",
  "action": "checkout.action.iwc",
  "request": {
    "payload": {
      "items": { "type": "array", "required": true, "minItems": 1, "items": { "type": "object", "fields": { "id": { "type": "string", "required": true }, "quantity": { "type": "integer", "required": true, "min": 1 } } } },
      "address": { "type": "string", "required": true, "maxLength": 200 }
    }
  },
  "response": { "fields": { "orderId": "string", "total": "number" } },
  "security": { "auth": true, "rateLimit": "10/1m" }
}

The action receives the payload, the query parameters and the path parameters as input. Its return value is the response. See actions.

A workflow transition

{
  "name": "shipOrder",
  "method": "POST",
  "path": "/orders/:id/ship",
  "workflow": "order.workflow.iwc",
  "transition": "ship",
  "security": { "auth": true, "roles": ["admin"] }
}

Moves record :id through the transition. It answers 409 if the record is not in a from state.

Idempotency keys

A phone that loses its connection mid-checkout retries. With "idempotency": "required", every request must carry an Idempotency-Key header (8–128 letters, digits, -, _; a fresh random value per operation, reused for its retries):

{
  "name": "checkout",
  "method": "POST",
  "path": "/checkout",
  "action": "checkout.action.iwc",
  "request": { "payload": { "note": { "type": "string" } } },
  "security": { "auth": true, "idempotency": "required" }
}

Keys are scoped to the app, the API and the signed-in user. A 5xx response isn't stored, so a retry runs again. "optional" applies all this only when the header is present. For operations that must never happen twice even across a server crash, also store the key on the record with a unique constraint (an order's idempotencyKey).

Rate limits per user or per value

{
  "name": "otp",
  "method": "POST",
  "path": "/otp/check",
  "action": "otp.action.iwc",
  "request": { "payload": { "phone": { "type": "string", "required": true } } },
  "security": { "auth": false, "rateLimit": { "rate": "5/10m", "per": ["ip", "=input.phone"] } }
}

Each per entry is its own bucket, and all must allow the request: ip, user (signed-out callers count per IP), or an expression over input and user. Values are stored hashed, and an entry whose value is empty doesn't apply. With "rateLimit": {"store": "database"} in .security.iwc, counters live in the database, so every server instance shares them.

Webhooks: raw body and headers

Signatures are computed over the exact bytes a provider sent, which re-encoding the parsed JSON wouldn't reproduce:

{
  "name": "paymentWebhook",
  "method": "POST",
  "path": "/webhooks/payments",
  "action": "payment-webhook.action.iwc",
  "request": {
    "rawBody": true,
    "headers": { "X-Signature": "HMAC-SHA256 of the body" },
    "payload": { "eventId": { "type": "string", "required": true }, "amountPaise": { "type": "integer", "required": true } }
  },
  "security": { "auth": false, "csrf": false }
}

The action receives input.rawBody and input.headers['x-signature']; they can't be supplied through the payload. Verify them with verifyHmacSecret, or an integration's verifyWebhook (packages).

A provider's event (Stripe, Razorpay, WhatsApp…) is large, nested and differs by type. Leave payload out and the API accepts any body: the action then gets only input.rawBody and the declared headers, so nothing unverified becomes an input field. verifyWebhook returns the parsed event once the signature holds.

Spreadsheets: CSV out and in

An API whose answer is a list can answer it as a CSV download instead of JSON:

{
  "name": "exportProducts",
  "method": "GET",
  "path": "/products.csv",
  "action": "export-products.action.iwc",
  "response": {
    "format": "csv",
    "filename": "products.csv",
    "columns": ["sku", { "field": "name", "label": "Product" }, { "field": "category.name", "label": "Category" }, { "field": "price", "label": "Price" }]
  },
  "security": { "auth": true, "permissions": ["products.export"] }
}

columns sets the order and headings (a field, or {field, label} with a dot path into nested values); without it every field is a column, alphabetically. A cell that a spreadsheet would run as a formula (starting =, +, -, @, a tab or a carriage return) gets a leading apostrophe, so text a visitor typed can't run in whoever opens the file. Numbers are written as numbers. An action can read up to 10,000 rows with a query step's limit.

To import, send the file's text in a JSON field (a widget can read a file the visitor picks) and parse it with parseCsv(text, delimiter?): the first row names the columns, each later row becomes {column: text} (trimmed; blank lines skipped; at most 5,000 rows). Inside a "transaction": true action, one bad row rolls the whole import back:

{ "operation": "forEach", "items": "parseCsv(input.csv)", "as": "row", "steps": [
  { "operation": "require", "condition": "number(row.price) > 0", "error": "=concat('Row ', row.sku, ': the price must be positive')" },
  { "operation": "create", "resource": "product.schema.iwc", "values": { "sku": "=row.sku", "name": "=row.name", "price": "=number(row.price)" } }
] }

Field specs

The same shape is used for request.payload, request.query, action input, event payload and component props:

{ "type": "string", "required": true, "minLength": 2, "maxLength": 80, "pattern": "^[A-Za-z ]+$", "trim": true, "description": "Display name" }

Query parameters arrive as strings and are converted ("2" becomes 2 for an integer, "true" becomes true).

Errors

Every error has one shape:

{ "error": { "code": "validation_failed", "message": "Some fields are invalid", "fields": { "email": "is required" } } }

Calling APIs

• From forms (submit.api), buttons (action: "api") and data sources (API.<name>), IWC handles sessions and CSRF for you.
• From other clients: send JSON, and either a session cookie plus the X-IWC-CSRF header, or Authorization: Bearer <token> with the token returned by auth.login/auth.register (bearer requests need no CSRF token). Declare token in the login API's response.fields to return it. A bearer token that is expired, revoked or from another app gets 401 with WWW-Authenticate: Bearer error="invalid_token", so the client knows to sign in again.
• A client that doesn't render pages (a phone app, a script, an API-only project) gets its CSRF token from GET /_iwc/csrf → {"csrf": "…"}, which also sets the cookie the token pairs with. Send both on the next write, typically the sign-in. Pages on other origins can't read this response.

jar=$(mktemp); tok=$(curl -s -c $jar localhost:3000/_iwc/csrf | sed 's/.*"csrf":"\([^"]*\)".*/\1/')
curl -s -b $jar -H "X-IWC-CSRF: $tok" -H 'Content-Type: application/json' \
  -d '{"email":"maya@example.com","password":"…"}' localhost:3000/api/auth/login

• Every API is documented at /_iwc/openapi.json (OpenAPI 3.1) and explorable at /_iwc/api-docs in development (below).
• A client on another origin needs that origin in .security.iwc cors.origins. It may then send Content-Type, Authorization, X-IWC-CSRF, Idempotency-Key and every header an API declares in request.headers, and read Retry-After, Idempotent-Replayed, WWW-Authenticate and Content-Disposition in answers.

curl -s localhost:3000/api/products?sort=-price&limit=2

File uploads

{ "name": "upload", "method": "POST", "path": "/uploads", "operation": "storage.upload", "security": { "auth": true } }

The form (or client) sends multipart/form-data with the file in a field named file:

{ "type": "form", "inputs": [{ "name": "file", "type": "file", "label": "Photo", "accept": "image/*" }], "submit": { "api": "upload.api.iwc", "label": "Upload" } }

The response is {"id", "url", "name", "mime", "size"}; the file is served at url (/_iwc/files/<id>). The size limit and allowed types come from app.storage. The type is detected from the file's bytes, not its name, and scriptable types (HTML, SVG, JavaScript) are always refused.

Versions

Two versions of an endpoint can be served side by side while clients move over:

{
  "name": "getOrderV2",
  "version": "v2",
  "method": "GET",
  "path": "/orders/:id",
  "operation": "db.get",
  "resource": "order.schema.iwc",
  "response": { "fields": { "id": "string", "status": "string", "total": "number" } },
  "security": { "auth": true }
}

This is /api/v2/orders/:id; an API without version keeps its plain /api/... address, so adding versions never moves existing clients. Mark the old one "deprecated": true to say so in the documentation. Forms, buttons and data sources that name a versioned API call its versioned address.

API documentation

IWC documents every API from its definition. Nothing is written twice: the request contract, validation rules, response fields, status codes and security come from the same declarations the server enforces, and the request-body rules are produced by the very function that validates requests.

What the document says, and where it comes from:

Nothing secret is included: no sensitive fields, credentials, environment values, action steps or provider settings.

Configure it in app.iwc:

{
  "name": "Atlas",
  "apiDocs": {
    "title": "Atlas API",
    "description": "Orders, catalogue and accounts.",
    "version": "2.1.0",
    "servers": [{ "url": "https://api.atlas.example", "description": "Production" }],
    "tags": { "orders": "Placing and tracking orders" },
    "contact": { "email": "api@atlas.example" },
    "spec": "always",
    "ui": "development"
  }
}

spec and ui take always, development or never. Without servers, the live document lists the server that answered (with its base path) and iwc make uses --server, seo.siteUrl or http://localhost:3000.

Common mistakes