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 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.