Back to Details

building-apis

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<!-- TIER:1 -->
<!-- TIER:1 -->

Building APIs

构建API

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.
API是一种RESTful endpoint，对外暴露供外部调用的集成逻辑。外部系统通过HTTP调用该API；API通过查询和导入处理请求，然后返回结构化响应。构建API时需要关注以下事项：
  • 模式选择——构建器（可视化配置）vs 脚本（完全JavaScript控制）
  • 请求定义——HTTP方法、URI路径、参数、请求体 schema、请求转换
  • 处理流水线——执行业务逻辑的路由器和页面处理器（查询+导入）
  • 响应路由——根据成功/失败状态或自定义条件，将处理后的数据导向正确的响应定义
  • 响应塑造——每个响应的状态码、字段映射、响应体 schema、钩子（preMap、postMap）
  • 响应映射——从每个页面处理器的响应中提取字段，放回记录供下游步骤使用。在每个
    pageProcessors[]
    条目上配置，与流程中的配置方式相同。对于查询导出，响应包含
    data[]
    和
    errors[]
    （单结果使用
    data[0].fieldName
    ）。对于导入，响应通过
    _json
    获取（使用
    _json.fieldName
    ）
  • postResponseMap钩子——响应映射后的JavaScript处理，配置在
    pageProcessors[]
    条目上
API与流程、工具一起用于各类集成场景。API没有独立的认证机制——传入请求通过Celigo API令牌进行认证；对外部系统的出站调用使用流水线中导出/导入所引用的连接。

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由外部HTTP调用者触发——没有上游导出、调度器或监听器为其提供数据。这带来三个设计影响：
  • 请求阶段为输入格式。调用者发送的所有内容（请求体、路径参数、查询参数、请求头）就是下游处理所看到的记录。没有上游流水线先对其进行重塑——如果需要在路由前重塑请求结构，请使用请求
    transform
    。
  • 响应阶段为输出结果。所选响应定义生成的内容就是调用者收到的内容。响应之后没有其他操作。
  • 无法自动启动。API没有
    schedule
    、监听器，也没有流程运行时控制项（
    proceedOnFailure
    、
    skipRetries
    、链式调用）。“每天凌晨2点执行X”属于流程范畴——流程可以调用API，但调度配置在流程上。失败后重试由调用者决定。
当流程需要调用API时，它会作为普通HTTP调用者（指向API URL的HTTP导出/导入）进行调用。不存在特殊的流程步骤到API的连接机制。
设置顶层
disabled: true
可让API下线而无需删除——调用者会收到404错误，直到API重新启用。

API Modes

API模式

Builder Mode (
type: "builder"
)

构建器模式（
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 (type: "builder")
+-- request            -- 方法、relativeURI、参数、bodySchema、mockRequest、transform
+-- routers[]          -- 处理流水线（与流程路由器结构相同）
|   +-- branches[]
|       +-- inputFilter        -- 何时使用该分支（s-expression规则）
|       +-- pageProcessors[]   -- 查询（导出）和导入
|       +-- nextRouterId       -- 链接到下一个路由器，或设为"apiRouter"结束
+-- responseRouter     -- id="apiRouter"，将处理后的数据路由到响应
+-- responses[]        -- 成功、失败、自定义——每个都包含statusCode、inputFilter、映射
传入的HTTP请求替代导出作为数据源。路由器和页面处理器的工作方式与流程完全相同。

API Execution Pipeline (Builder Mode)

构建器模式下的API执行流水线

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
当API收到请求时：
  1. 接收请求——将请求方法+路径与API端点定义匹配
  2. 请求转换（可选）——在路由前重塑传入的请求体
  3. 路由器评估——
    routeRecordsUsing
    评估分支的输入过滤条件
  4. 分支选择——第一个匹配的分支处理请求
  5. 页面处理器——分支中的每个处理器按顺序执行（导出查询、导入写入）
  6. 响应映射——每个处理器上的
    responseMapping
    将数据传递给下一个处理器
  7. 响应路由器——
    responseRouter
    （id="apiRouter"）根据响应输入过滤器选择要使用的响应模板
  8. 返回响应——将所选响应模板及其statusCode、请求头、响应体返回给调用者

Script Mode (
type: "script"
)

脚本模式（
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.
单个
handleRequest
JavaScript函数接收请求对象（method、headers、queryParams、body、pathParams）并返回
{statusCode, headers, body}
。无需可视化配置，完全可控。
遗留API（无
type
字段，顶层包含
_scriptId
+ 
function
）仍在生产环境中使用，但未在当前规范中体现。判断方式：如果
type
不存在/为null且存在
_scriptId
，则为遗留API。

Quick Reference

快速参考

Decision Matrix

决策矩阵

ScenarioModeWhy
Standard lookup/write with structured responseBuilderVisual debugging, test runs, structured responses
Multiple response shapes based on success/failureBuilderResponse router + inputFilter handles this declaratively
Complex conditional logic or custom auth validationScriptFull JavaScript control over request/response
Dynamic routing that can't be expressed as input filtersScript
handleRequest
can implement arbitrary logic
Proxy through an authenticated connectionBuilderWire the connection's export/import as a page processor
Simple webhook receiver that transforms and forwardsBuilderSingle router, single branch, one import
场景模式原因
带结构化响应的标准查询/写入构建器可视化调试、测试运行、结构化响应
基于成功/失败状态的多种响应格式构建器响应路由器+inputFilter可声明式处理
复杂条件逻辑或自定义认证验证脚本完全控制请求/响应的JavaScript能力
无法用输入过滤器表达的动态路由脚本
handleRequest
可实现任意逻辑
通过已认证连接代理请求构建器将连接的导出/导入作为页面处理器配置
转换并转发的简单Webhook接收器构建器单个路由器、单个分支、一个导入

Minimum Required Fields

必填字段

ModeRequired Fields
Builder
name
, 
type: "builder"
, 
builder.request
(method + relativeURI)
Script
name
, 
type: "script"
, 
script._scriptId
, 
script.function
Legacy
name
, 
_scriptId
, 
function
(no 
type
field)
模式必填字段
构建器
name
、
type: "builder"
、
builder.request
（method + relativeURI）
脚本
name
、
type: "script"
、
script._scriptId
、
script.function
遗留
name
、
_scriptId
、
function
（无
type
字段）

Schema Index

Schema索引

All schemas are in references/schemas/:
SchemaWhat it defines
request.ymlTop-level API fields (name, type, version, disabled, builder/script refs)
response.ymlAPI response shape
builder.ymlBuilder configuration (request, routers, responseRouter, responses refs)
api-request.ymlRequest config (method, relativeURI, params, bodySchema, mockRequest, transform)
api-response.ymlResponse definitions (id, name, type, statusCode, inputFilter, mappings, hooks)
response-router.ymlResponse router (id="apiRouter", routeRecordsUsing)
router.ymlRouters (branches, inputFilter, pageProcessors)
script.ymlScript config (_scriptId, function)
apim.ymlAPIM metadata (publication status)
shipworks.ymlLegacy ShipWorks auth
所有Schema都在references/schemas/中：
Schema定义内容
request.yml顶层API字段（名称、类型、版本、禁用状态、构建器/脚本引用）
response.ymlAPI响应格式
builder.yml构建器配置（请求、路由器、响应路由器、响应引用）
api-request.yml请求配置（方法、relativeURI、参数、bodySchema、mockRequest、transform）
api-response.yml响应定义（id、名称、类型、statusCode、inputFilter、映射、钩子）
response-router.yml响应路由器（id="apiRouter"、routeRecordsUsing）
router.yml路由器（分支、inputFilter、pageProcessors）
script.yml脚本配置（_scriptId、function）
apim.ymlAPIM元数据（发布状态）
shipworks.yml遗留ShipWorks认证

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
  • writing-handlebars > Quick Reference -- dynamic expressions in request bodies, URIs, and response mappings
  • configuring-filters > Quick Reference -- input filters on router branches to conditionally route records
<!-- TIER:2 -->
  • configuring-exports > 快速参考——构建API流水线中用作页面处理器的查询导出
  • configuring-imports > 快速参考——构建API流水线中用作页面处理器的导入
  • building-flows > 如何构建流程——流程与API共享相同的路由器/分支/pageProcessor流水线机制
  • writing-scripts > 快速参考——编写
    handleRequest
    （脚本模式API）、
    preMap
    /
    postMap
    钩子和
    postResponseMap
  • writing-handlebars > 快速参考——请求体、URI和响应映射中的动态表达式
  • configuring-filters > 快速参考——路由器分支上的输入过滤器，用于条件路由记录
<!-- TIER:2 -->

How to Build an API

如何构建API

1. Plan what the API needs to do

1. 规划API的功能

Before creating anything, understand the requirements: what endpoint the caller needs, what data it sends, what systems are involved, what the response should look like. This determines everything -- mode, pipeline shape, which connections/exports/imports are needed.
创建前，先明确需求：调用者需要什么端点、发送什么数据、涉及哪些系统、响应应是什么格式。这将决定所有事项——模式、流水线结构、所需的连接/导出/导入。

2. Decide the mode

2. 选择模式

Use builder for most APIs -- it provides visual debugging, test runs, and structured responses. Use script only when the processing logic is too dynamic for the visual pipeline (e.g., complex conditional responses, custom auth validation, dynamic routing).
大多数API使用构建器模式——它提供可视化调试、测试运行和结构化响应。仅当处理逻辑过于动态，无法用可视化流水线实现时（例如复杂条件响应、自定义认证验证、动态路由），才使用脚本模式。

3. Check for existing resources

3. 检查现有资源

Look for connections, exports, and imports that can be reused before creating new ones.
bash
undefined
创建新资源前，先寻找可复用的连接、导出和导入。
bash
undefined

Search across all resource types in the account

在账户中搜索所有资源类型

celigo account search "<keyword>"
celigo account search "<keyword>"

Show what an existing API uses (exports, imports, connections)

查看现有API使用的资源（导出、导入、连接）

celigo account dependencies api <id>
celigo account dependencies api <id>

Find orphaned resources that could be reused

查找可复用的孤立资源

celigo account lint
celigo account lint

Search for APIs already in the account for patterns

搜索账户中已有的API，寻找参考模式

celigo apis list | grep -i "<keyword>"
celigo apis list | grep -i "<keyword>"

Check existing exports/imports that could serve as pipeline steps

检查可作为流水线步骤的现有导出/导入

celigo exports list | grep -i "<system-name>" celigo imports list | grep -i "<system-name>"
celigo exports list | grep -i "<system-name>" celigo imports list | grep -i "<system-name>"

Search marketplace for pre-built integration templates

在市场中搜索预构建的集成模板

celigo templates marketplace

The account index auto-refreshes when stale (>4 hours). Force a fresh snapshot with `celigo account snapshot`.
celigo templates marketplace

账户索引会在过时（超过4小时）时自动刷新。使用`celigo account snapshot`强制生成新快照。

4. Create the supporting resources (bottom-up)

4. 创建支撑资源（自底向上）

APIs reference exports and imports as page processors -- these must exist before you can attach them. Build order:
  1. Connections -- create or reuse connections to the target systems
  2. Exports -- for lookups that query external systems (use 
    configuring-exports
    skill)
  3. Imports -- for writes to external systems (use 
    configuring-imports
    skill)
API将导出和导入作为页面处理器引用——这些资源必须先存在，才能附加到API。构建顺序：
  1. 连接——创建或复用与目标系统的连接
  2. 导出——用于查询外部系统（使用
    configuring-exports
    技能）
  3. 导入——用于写入外部系统（使用
    configuring-imports
    技能）

5. Define the request (builder mode)

5. 定义请求（构建器模式）

Choose the HTTP method and URI path. GET and POST are most common; PUT and PATCH are rare.
  • Path parameters use colon notation: 
    /customers/:id
  • Document query parameters, path parameters, headers, and body schema
  • Add a 
    mockRequest
    for testing the pipeline without live calls
  • Optionally add a request 
    transform
    (expression-based or script-based) to reshape incoming data before processing
选择HTTP方法和URI路径。GET和POST最常用；PUT和PATCH较少使用。
  • 路径参数使用冒号表示法：
    /customers/:id
  • 记录查询参数、路径参数、请求头和请求体schema
  • 添加
    mockRequest
    用于在无需实际调用的情况下测试流水线
  • 可选添加请求
    transform
    （基于表达式或脚本），在处理前重塑传入数据

6. Build the processing pipeline

6. 构建处理流水线

The pipeline is made of routers, branches, and page processors. See router.yml for the full schema.
Every builder API needs at least one router -- it's the container that holds branches, and branches hold the page processors that do the actual work. Use multiple branches when different request conditions need different processing paths (e.g., branch by HTTP method, request field value, or record type). Use multiple routers when you need sequential stages of processing where each stage can branch independently.
For pass-through routers (single branch, no filters, just linear steps before a branching router), omit 
routeRecordsTo
and 
routeRecordsUsing
-- including them makes it appear as a filter-based branch in the UI. The API defaults are sufficient.
Input filters use s-expression syntax: 
["operator", ["type", ["extract", "field"]], value]
. Type wrappers (
string
, 
number
, 
boolean
) are required around 
extract
and 
context
accessors. Logical combinators: 
["and", cond1, cond2]
, 
["or", cond1, cond2]
.
The last branch in the chain must set 
nextRouterId: "apiRouter"
to reach the response router.
流水线由路由器、分支和页面处理器组成。完整Schema请查看router.yml。
每个构建器模式API至少需要一个路由器——它是容纳分支的容器，分支包含执行实际工作的页面处理器。当不同请求条件需要不同处理路径时（例如按HTTP方法、请求字段值或记录类型分支），使用多个分支。当需要多个独立分支的顺序处理阶段时，使用多个路由器。
对于直通路由器（单个分支、无过滤器，仅为分支路由器前的线性步骤），省略
routeRecordsTo
和
routeRecordsUsing
——添加这些会使其在UI中显示为基于过滤器的分支。API默认配置已足够。
输入过滤器使用s-expression语法：
["operator", ["type", ["extract", "field"]], value]
。
extract
和
context
访问器必须包裹在类型包装器（
string
、
number
、
boolean
）中。逻辑组合器：
["and", cond1, cond2]
、
["or", cond1, cond2]
。
链中的最后一个分支必须设置
nextRouterId: "apiRouter"
以到达响应路由器。

7. Configure responses

7. 配置响应

Every builder API needs exactly one 
success
response and one 
fail
response. Add 
custom
responses for specific scenarios (e.g., 404 not found, 422 validation error).
Each response has:
  • statusCode
    (HTTP status code)
  • inputFilter
    to determine when it's selected (typically 
    ["equals", ["boolean", ["context", "success"]], true]
    for success)
  • mappings
    to shape the response body from the processed record
  • Optional 
    bodySchema
    for documentation, 
    headers
    , 
    lookups
    , and 
    hooks
    (preMap, postMap)
每个构建器模式API必须有一个
success
响应和一个
fail
响应。可为特定场景添加
custom
响应（例如404未找到、422验证错误）。
每个响应包含：
  • statusCode
    （HTTP状态码）
  • inputFilter
    用于确定何时选择该响应（成功响应通常使用
    ["equals", ["boolean", ["context", "success"]], true]
    ）
  • mappings
    用于根据处理后的记录塑造响应体
  • 可选的
    bodySchema
    （用于文档）、
    headers
    、
    lookups
    和
    hooks
    （preMap、postMap）

8. Configure the response router

8. 配置响应路由器

Set 
id: "apiRouter"
and choose routing method:
  • input_filters
    (default) -- evaluates each response's 
    inputFilter
  • script
    -- custom JavaScript returns the response 
    id
    to use
设置
id: "apiRouter"
并选择路由方式：
  • input_filters
    （默认）——评估每个响应的
    inputFilter
  • script
    ——自定义JavaScript返回要使用的响应
    id

9. Build the JSON

9. 构建JSON

Reference the Schema Index above for exact field schemas.
Every API needs at minimum: 
name
, 
type
, and either 
builder
(with 
request
) or 
script
(with 
_scriptId
and 
function
).
参考上方的Schema索引获取准确的字段Schema。
每个API至少需要：
name
、
type
，以及
builder
（包含
request
）或
script
（包含
_scriptId
和
function
）。

The Response and Routing Model

响应与路由模型

Once the routers finish processing, the API selects which response to return and shapes its body. This is where APIs diverge most from flows -- the routing is narrower, and "mapping" happens at two distinct layers.
路由器完成处理后，API会选择要返回的响应并塑造其响应体。这是API与流程最大的不同之处——路由范围更窄，“映射”发生在两个不同的层级。

Branch selection and router chaining

分支选择与路由器链式调用

APIs support a single routing strategy: 
first_matching_branch
. Within a router, each record is evaluated against the branches in order and taken by the first branch whose 
inputFilter
matches; that record then follows only that branch. (Flows also offer 
all_matching_branches
, which fans one record out to every matching branch -- APIs never do this. A record takes exactly one branch per router.)
Each branch's 
nextRouterId
decides where the record goes after that branch's page processors finish:
  • Another router's 
    id
     -- chain into that router for a further stage of processing.
  • "apiRouter"
     -- hand off to the response router (whose reserved 
    id
    is always 
    apiRouter
    ) to finish.
Chaining lets you express sequential stages where each stage branches independently; the last branch in the chain sets 
nextRouterId: "apiRouter"
to reach the response router.
API仅支持一种路由策略：
first_matching_branch
。在路由器内，每条记录会按顺序评估分支，被第一个匹配
inputFilter
的分支接收；然后该记录仅沿该分支处理。（流程还支持
all_matching_branches
，即一条记录会分发到所有匹配的分支——API从不使用这种方式。每条记录在每个路由器中仅走一个分支。）
每个分支的
nextRouterId
决定记录在该分支的页面处理器完成后去向：
  • 另一个路由器的
    id
    ——链接到该路由器进行下一阶段处理。
  • "apiRouter"
    ——移交到响应路由器（其保留
    id
    始终为
    apiRouter
    ）以完成处理。
链式调用可用于表达每个阶段独立分支的顺序处理；链中的最后一个分支设置
nextRouterId: "apiRouter"
以到达响应路由器。

Response selection -- success, fail, custom

响应选择——成功、失败、自定义

Every builder API has exactly one 
success
response, exactly one 
fail
response, and zero or more 
custom
responses (the response's 
type
field). The response router (
id: "apiRouter"
) picks one after processing completes:
  • success
     -- the happy path, returned when processing completed and no 
    custom
    response matched. Conventionally a 2xx 
    statusCode
    (
    200
    , or 
    201
    when the API created something).
  • fail
     -- the error path. Processing errors (a lookup returned a 500, an import got a 4xx, a script threw) are routed here automatically. Conventionally a 4xx/5xx 
    statusCode
    (
    400
    or 
    500
    ); its 
    mappings
    surface the error message and any context the caller needs.
  • custom
     -- a non-error, non-default response selected by its own 
    inputFilter
    . Reach for one when the outcome fits neither 
    success
    nor 
    fail
    , when the 
    statusCode
    differs, or when the body shape differs. Typical cases: 
    • 404
      not found       -- the lookup ran but returned zero records (filter: the results array is empty).
    • 409
      conflict       -- the destination rejected a create because the record already exists.
    • 202
      accepted       -- processing started a background job; tell the caller "received, working on it."
    • Conditional body -- a different shape driven by a query parameter (e.g. 
      ?format=summary
      vs 
      ?format=full
      ).
In 
input_filters
mode the response router returns the first response whose 
inputFilter
matches, so list 
custom
responses ahead of 
success
to let their specific conditions win. In 
script
mode a JavaScript function inspects the record and returns the response 
id
to use.
每个构建器模式API有且仅有一个
success
响应、一个
fail
响应，以及零个或多个
custom
响应（由响应的
type
字段标识）。响应路由器（
id: "apiRouter"
）在处理完成后选择一个响应：
  • success
    ——正常路径，当处理完成且无匹配的
    custom
    响应时返回。通常使用2xx状态码（
    200
    ，或API创建资源时使用
    201
    ）。
  • fail
    ——错误路径。处理错误（查询返回500、导入收到4xx、脚本抛出异常）会自动路由到此处。通常使用4xx/5xx状态码（
    400
    或
    500
    ）；其
    mappings
    会展示错误消息和调用者需要的上下文。
  • custom
    ——非错误、非默认的响应，由自身的
    inputFilter
    选择。当结果既不属于
    success
    也不属于
    fail
    、状态码不同或响应体格式不同时使用。典型场景： 
    • 404
      未找到      ——查询执行但未返回任何记录（过滤器：结果数组为空）。
    • 409
      冲突      ——目标系统因记录已存在而拒绝创建请求。
    • 202
      已接受      ——处理启动了后台任务；告知调用者“已接收，正在处理”。
    • 条件响应体——由查询参数驱动的不同格式（例如
      ?format=summary
      vs 
      ?format=full
      ）。
在
input_filters
模式下，响应路由器返回第一个匹配
inputFilter
的响应，因此请将
custom
响应列在
success
之前，使其特定条件优先匹配。在
script
模式下，JavaScript函数检查记录并返回要使用的响应
id
。

statusCode
vs the response 
type

statusCode
与响应
type
的区别

These are independent and often conflated:
  • The response 
    type
     (
    success
    / 
    fail
    / 
    custom
    ) is Celigo's internal classification -- it drives which response the response router selects.
  • The 
    statusCode
     is the HTTP status the caller receives -- it lives on the response definition.
A 
custom
response can carry any 
statusCode
(the "not found" response returns 
404
; the "async accepted" response returns 
202
), and 
success
is conventionally 2xx but doesn't have to be. So "return a 
404
when the customer isn't found" means adding a 
custom
response with 
statusCode: 404
and an 
inputFilter
that matches when the lookup's results array is empty -- not editing the 
success
response.
两者相互独立，常被混淆：
  • 响应**
    type
    **（
    success
    / 
    fail
    / 
    custom
    ）是Celigo的内部分类——决定响应路由器选择哪个响应。
  • **
    statusCode
    **是调用者收到的HTTP状态码——定义在响应配置中。
custom
响应可携带任意
statusCode
（“未找到”响应返回
404
；“异步已接受”响应返回
202
），
success
通常使用2xx状态码，但并非必须。因此“当客户不存在时返回
404
”意味着添加一个
custom
响应，设置
statusCode: 404
并配置匹配查询结果数组为空的
inputFilter
——而非修改
success
响应。

The two mapping layers

两个映射层级

"Mapping" refers to two different things at two layers, and conflating them is the most common source of confusion when building APIs.
1. Page-processor 
responseMapping
(record enrichment). Configured on a lookup or import inside a router branch -- the same shape as a flow's page-processor 
responseMapping
. It pulls fields off that page processor's response and merges them onto the record so downstream routers, page processors, and response mappings can see them. It does not shape the HTTP body.
{
  "fields": [
    {"extract": "id", "generate": "customerId"},
    {"extract": "accountStatus", "generate": "status"}
  ]
}
2. Response-stage 
mappings
(HTTP body). Configured on a 
success
/ 
fail
/ 
custom
response (alongside its 
lookups
and 
hooks
). It reads the now-enriched record and builds the HTTP response body returned to the caller.
{
  "mappings": [
    {"extract": "customerId", "generate": "data.id"},
    {"extract": "status", "generate": "data.status"}
  ]
}
The two work together: the lookup's 
responseMapping
merges 
customerId
onto the record, then the response's 
mappings
place 
customerId
into the body's 
data.id
. A field the page processor returned must first be carried onto the record by a 
responseMapping
before a response 
mapping
can extract it. When unsure which layer you need, ask: does this step add the field to the record (page-processor 
responseMapping
) or read the field off the record into the body (response 
mappings
)?
“映射”指两个不同层级的不同操作，混淆两者是构建API时最常见的困惑来源。
1. 页面处理器
responseMapping
（记录增强）。配置在路由器分支中的查询或导入上——与流程中页面处理器的
responseMapping
格式相同。它从页面处理器的响应中提取字段，合并到记录中，供下游路由器、页面处理器和响应映射使用。它不塑造HTTP响应体。
{
  "fields": [
    {"extract": "id", "generate": "customerId"},
    {"extract": "accountStatus", "generate": "status"}
  ]
}
2. 响应阶段
mappings
（HTTP响应体）。配置在
success
/ 
fail
/ 
custom
响应上（与
lookups
和
hooks
一起）。它读取已增强的记录，构建返回给调用者的HTTP响应体。
{
  "mappings": [
    {"extract": "customerId", "generate": "data.id"},
    {"extract": "status", "generate": "data.status"}
  ]
}
两者协同工作：查询的
responseMapping
将
customerId
合并到记录中，然后响应的
mappings
将
customerId
放入响应体的
data.id
中。页面处理器返回的字段必须先通过
responseMapping
添加到记录中，响应
mappings
才能提取它。不确定需要哪个层级时，可问自己：此步骤是将字段添加到记录中（页面处理器
responseMapping
）还是从记录中读取字段到响应体（响应
mappings
）？

CLI Commands

CLI命令

bash
undefined
bash
undefined

CRUD

CRUD操作

celigo apis list celigo apis get <id> celigo apis create < api.json celigo apis update <id> < api.json celigo apis set <id> key=value [key2=value2 ...] celigo apis delete <id>
celigo apis list celigo apis get <id> celigo apis create < api.json celigo apis update <id> < api.json celigo apis set <id> key=value [key2=value2 ...] celigo apis delete <id>

Clone (builder-mode only)

克隆（仅支持构建器模式）

celigo apis clone <id> --api-version <version> [--name <name>] [--description <desc>] [--environment <envId>]
celigo apis clone <id> --api-version <version> [--name <name>] [--description <desc>] [--environment <envId>]

Pipeline management

流水线管理

celigo apis add-processor <id> <exportOrImportId> [--router <routerId>] [--branch <branchName>] celigo apis remove-processor <id> <exportOrImportId> [--router <routerId>] [--branch <branchName>]
celigo apis add-processor <id> <exportOrImportId> [--router <routerId>] [--branch <branchName>] celigo apis remove-processor <id> <exportOrImportId> [--router <routerId>] [--branch <branchName>]

Logs

日志

celigo apis logs <id> celigo apis log-detail <id> <key>
celigo apis logs <id> celigo apis log-detail <id> <key>

Test run

测试运行

celigo apis test-run <id> celigo apis test-run-step-results <id> <runId> <exportOrImportId> celigo apis test-run-step-logs <id> <runId> <exportOrImportId>
celigo apis test-run <id> celigo apis test-run-step-results <id> <runId> <exportOrImportId> celigo apis test-run-step-logs <id> <runId> <exportOrImportId>

Debug (for exports/imports within the API pipeline)

调试（针对API流水线中的导出/导入）

celigo apis debug-requests <id> <exportOrImportId> [--since <minutes>] celigo apis debug-request-detail <id> <exportOrImportId> <key>
celigo apis debug-requests <id> <exportOrImportId> [--since <minutes>] celigo apis debug-request-detail <id> <exportOrImportId> <key>

Discovery

资源发现

celigo account search "<keyword>" celigo templates marketplace

<!-- TIER:3 -->
celigo account search "<keyword>" celigo templates marketplace

<!-- TIER:3 -->

Pre-Submit Checklist

提交前检查清单

Before creating or updating an API, verify:
  • name
    is set and descriptive
  • type
    is 
    "builder"
    or 
    "script"
    (not omitted, which creates a legacy API)
  • Builder mode: 
    builder.request.method
    and 
    builder.request.relativeURI
    are set
  • Builder mode: at least one router with at least one branch exists
  • Builder mode: last branch has 
    nextRouterId: "apiRouter"
  • Builder mode: both 
    success
    and 
    fail
    responses are defined
  • Builder mode: success response 
    inputFilter
    uses 
    ["equals", ["boolean", ["context", "success"]], true]
  • Script mode: 
    script._scriptId
    and 
    script.function
    reference a valid script
  • All 
    _exportId
    and 
    _importId
    references in page processors point to existing resources
  • Router IDs are unique within the API
  • version
    is set (it becomes part of the endpoint URL: 
    /{version}{relativeURI}
    )
  • Input filter expressions wrap 
    extract
    /
    context
    accessors in type wrappers (
    string
    , 
    number
    , 
    boolean
    )
创建或更新API前，请验证：
  • 设置了
    name
    且描述清晰
  • type
    设为
    "builder"
    或
    "script"
    （不省略，否则会创建遗留API）
  • 构建器模式：已设置
    builder.request.method
    和
    builder.request.relativeURI
  • 构建器模式：至少存在一个路由器和一个分支
  • 构建器模式：最后一个分支设置了
    nextRouterId: "apiRouter"
  • 构建器模式：已定义
    success
    和
    fail
    响应
  • 构建器模式：成功响应的
    inputFilter
    使用
    ["equals", ["boolean", ["context", "success"]], true]
  • 脚本模式：
    script._scriptId
    和
    script.function
    引用有效的脚本
  • 页面处理器中所有
    _exportId
    和
    _importId
    引用都指向现有资源
  • 路由器ID在API内唯一
  • 设置了
    version
    （它会成为端点URL的一部分：
    /{version}{relativeURI}
    ）
  • 输入过滤器表达式将
    extract
    /
    context
    访问器包裹在类型包装器（
    string
    、
    number
    、
    boolean
    ）中

Gotchas

常见陷阱

  1. PUT erases omitted fields. Always GET first, modify, then PUT. The 
    set
    command handles this automatically.
  2. APIs only support 
    first_matching_branch
    routing.     Unlike flows which also support 
    all_matching_branches
    , API routers always stop at the first matching branch.
  3. Omitting 
    inputFilter
    type wrappers silently fails.     Use 
    ["boolean", ["context", "success"]]
    , not bare 
    ["context", "success"]
    -- the filter will never match without the wrapper.
  4. Clone only works for builder-mode APIs. Script and legacy APIs cannot be cloned via the CLI.
  5. Missing a success or fail response causes undefined behavior. The response router won't know where to route.
  6. **version
    becomes part of the URL path.** The full endpoint is 
    /{version}{relativeURI}
    . Changing the version changes the URL that callers must use.
  7. Page-processor 
    responseMapping
    and response 
    mappings
    are different layers.     
    responseMapping
    enriches the record with fields from a page processor's response; a response's 
    mappings
    shape the HTTP body from that record. A field the lookup returned won't reach the body unless a 
    responseMapping
    first carries it onto the record.
  8. APIs don't start themselves. No 
    schedule
    , no listeners, no flow-level runtime controls, no abstract/instance templating. Scheduled or event-driven work belongs in a flow that calls the API.
  9. disabled: true
    returns 404 to callers.     Use it to pause an API without deleting it; re-enable with 
    disabled: false
    .
  1. PUT会删除未指定的字段。请始终先GET、修改，再PUT。
    set
    命令会自动处理此问题。
  2. API仅支持
    first_matching_branch
    路由    。与支持
    all_matching_branches
    的流程不同，API路由器始终在第一个匹配分支处停止。
  3. 省略inputFilter类型包装器会导致静默失败。请使用
    ["boolean", ["context", "success"]]
    ，而非直接使用
    ["context", "success"]
    ——没有包装器的过滤器永远不会匹配。
  4. 克隆仅适用于构建器模式API。脚本和遗留API无法通过CLI克隆。
  5. 缺少success或fail响应会导致未定义行为。响应路由器不知道该路由到哪里。
  6. version
    会成为URL路径的一部分    。完整端点为
    /{version}{relativeURI}
    。修改版本会改变调用者必须使用的URL。
  7. 页面处理器
    responseMapping
    和响应
    mappings
    是不同层级    。
    responseMapping
    用页面处理器响应中的字段增强记录；响应的
    mappings
    从该记录塑造HTTP响应体。查询返回的字段必须先通过
    responseMapping
    添加到记录中，才能被响应
    mappings
    提取。
  8. API无法自行启动。没有
    schedule
    、监听器、流程级运行时控制项、抽象/实例模板。定时或事件驱动的工作属于调用API的流程。
  9. disabled: true
    会向调用者返回404    。使用它暂停API而无需删除；设置
    disabled: false
    重新启用。

Common Errors

常见错误

ErrorCauseFix
404
on API endpoint		Wrong 
version
or 
relativeURI
in the request		Verify the full URL is 
/{version}{relativeURI}
and both match the API definition
422
validation error on create/update		Missing required fields or invalid field valuesCheck the Pre-Submit Checklist; verify 
type
is set
Response always returns the 
fail
response		Success 
inputFilter
is malformed or missing type wrapper		Use 
["equals", ["boolean", ["context", "success"]], true]
exactly
Response body is emptyResponse 
mappings
not configured or field paths don't match		Verify mapping extract paths match the actual processed record structure
Pipeline step silently skipped
inputFilter
on a branch evaluates to false for all records		Debug with 
celigo apis test-run-step-results
to see each step's input/output
Clone failed
error		Attempting to clone a script-mode or legacy APIClone is builder-mode only; recreate script APIs manually
Page processor returns no dataExport/import 
_id
reference is wrong or resource is disabled		Verify the referenced resource exists and is enabled with 
celigo exports get
/ 
celigo imports get
Router ID not found
error
nextRouterId
references a non-existent router ID		Ensure all 
nextRouterId
values match a real router 
id
or 
"apiRouter"
Response body missing a field the lookup returnedThe page-processor 
responseMapping
never carried the field onto the record		Add a 
responseMapping
entry (
{"fields": [{"extract": ..., "generate": ...}]}
) on the page processor so the response 
mappings
have it to extract
错误原因修复方法
API端点返回
404
请求中的
version
或
relativeURI
错误		验证完整URL为
/{version}{relativeURI}
，且两者与API定义匹配
创建/更新时返回
422
验证错误		缺少必填字段或字段值无效检查提交前检查清单；验证
type
已设置
响应始终返回
fail
响应		成功响应的
inputFilter
格式错误或缺少类型包装器		严格使用
["equals", ["boolean", ["context", "success"]], true]
响应体为空未配置响应
mappings
或字段路径不匹配		验证映射提取路径与实际处理后的记录结构匹配
流水线步骤被静默跳过分支上的
inputFilter
对所有记录都评估为false		使用
celigo apis test-run-step-results
调试，查看每个步骤的输入/输出
出现
Clone failed
错误		尝试克隆脚本模式或遗留API克隆仅支持构建器模式；手动重新创建脚本API
页面处理器未返回数据导出/导入的
_id
引用错误或资源已禁用		使用
celigo exports get
/ 
celigo imports get
验证引用的资源存在且已启用
出现
Router ID not found
错误
nextRouterId
引用了不存在的路由器ID		确保所有
nextRouterId
值匹配真实的路由器
id
或
"apiRouter"
响应体缺少查询返回的字段页面处理器的
responseMapping
从未将该字段添加到记录中		在页面处理器上添加
responseMapping
条目（
{"fields": [{"extract": ..., "generate": ...}]}
），使响应
mappings
可以提取该字段