building-apis

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 use id for the created record's ID and _json.fieldName for response-body fields
• 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 -- callers send a Celigo API token with full access or one scoped to the API (_apiIds; see managing-api-tokens > Access Scope Decision Matrix) to https://api.integrator.io/apis/{version}{relativeURI}; 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: