Building Apis

<!-- TIER:1 -->

Building APIs

An API is a RESTful endpoint that exposes integration logic for external consumption. External systems call the API over HTTP; the API processes the request through lookups and imports, then returns a structured response. Concerns when building an API:

• Mode selection -- builder (visual configuration) vs script (full JavaScript control)
• Request definition -- HTTP method, URI path, parameters, body schema, request transformation
• Processing pipeline -- routers and page processors (lookups + imports) that execute business logic
• Response routing -- directing processed data to the correct response definition based on success/failure or custom conditions
• Response shaping -- status codes, field mappings, body schema, hooks (preMap, postMap) on each response
• Response mapping -- extracting fields from each page processor's response back into the record for downstream steps. Configured on each pageProcessors[] entry, same as in flows. For lookup exports the response has data[] and errors[] (use data[0].fieldName for single results). For imports the response is via _json (use _json.fieldName)
• postResponseMap hook -- JavaScript processing after response mapping, configured on pageProcessors[] entries

Used across integrations alongside flows and tools. APIs do not have their own authentication -- incoming requests authenticate via the Celigo API token; outbound calls to external systems use the connections referenced by exports/imports in the pipeline.

The Request IS the Source Record

APIs are invoked by an external HTTP caller -- there is no upstream export, no scheduler, no listener feeding them. That has three design consequences:

• The request stage is the input shape. Whatever the caller sends (body, path params, query params, headers) is what downstream processing sees as the record. There is no upstream pipeline to reshape it first -- use the request transform if the envelope needs reshaping before routing.
• The response stage is the output. Whatever the selected response definition produces is exactly what the caller receives. Nothing runs after it.
• No self-starting. APIs have no schedule, no listener, and none of the flow runtime controls (proceedOnFailure, skipRetries, chaining). "Every night at 2 AM, do X" is a flow -- possibly one that calls the API, but the schedule lives on the flow. Retry-after-failure is the caller's decision.

When a flow needs to invoke an API, it does so as an ordinary HTTP caller (an HTTP export/import pointing at the API's URL). There is no special flow-step-to-API wiring.

A top-level disabled: true takes the API offline without deleting it -- callers get a 404 until it's re-enabled.

API Modes

Builder Mode (type: "builder")

Visual configuration with discrete components:

API (type: "builder")
+-- request            -- method, relativeURI, params, bodySchema, mockRequest, transform
+-- routers[]          -- processing pipeline (same structure as flow routers)
|   +-- branches[]
|       +-- inputFilter        -- when to use this branch (s-expression rules)
|       +-- pageProcessors[]   -- lookups (exports) and imports
|       +-- nextRouterId       -- chain to next router, or "apiRouter" to finish
+-- responseRouter     -- id="apiRouter", routes processed data to a response
+-- responses[]        -- success, fail, custom -- each with statusCode, inputFilter, mappings

The incoming HTTP request replaces the export as data source. Routers and page processors work identically to flows.

API Execution Pipeline (Builder Mode)

When an API receives a request:

1. Request received -- method + path matched against the API endpoint definition
2. Request transform (optional) -- reshapes the incoming request body before routing
3. Router evaluation -- routeRecordsUsing evaluates branch input filter conditions
4. Branch selection -- first matching branch processes the request
5. Page processors -- each processor in the branch executes sequentially (export lookups, import writes)
6. Response mapping -- responseMapping on each processor carries data forward to the next processor
7. Response router -- responseRouter (id="apiRouter") selects which response template to use based on response input filters
8. Response -- selected response template returned to the caller with its statusCode, headers, and body

Script Mode (type: "script")

A single handleRequest JavaScript function receives the request object (method, headers, queryParams, body, pathParams) and returns {statusCode, headers, body}. Complete control with no visual configuration.

Legacy APIs (no type field, top-level _scriptId + function) exist in production but are not represented in the current spec. Distinguish by: if type is absent/null and _scriptId is present, it's legacy.

Quick Reference

Decision Matrix

Minimum Required Fields

Schema Index

All schemas are in references/schemas/:

Related Skills

• configuring-exports > Quick Reference -- building lookup exports used as page processors in the API pipeline
• configuring-imports > Quick Reference -- building imports used as page processors in the API pipeline
• building-flows > How to Build a Flow -- flows share the same router/branch/pageProcessor pipeline mechanics
• writing-scripts > Quick Reference -- writing handleRequest (script-mode APIs), preMap/postMap hooks, and postResponseMap