@celigo/api-specs 0.2.11 → 0.2.13
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +70 -81
- package/dist/integration.yml +33 -0
- package/package.json +13 -1
- package/schemas.json +2 -2
package/README.md
CHANGED
|
@@ -1,12 +1,47 @@
|
|
|
1
|
-
|
|
1
|
+
<!--
|
|
2
|
+
This file ships as the README of the @celigo/api-specs npm package. Its audience is public, so it
|
|
3
|
+
must not describe repository internals or link into the repository. The repository README is
|
|
4
|
+
.github/README.md, which GitHub renders in place of this one.
|
|
5
|
+
-->
|
|
2
6
|
|
|
3
|
-
|
|
4
|
-
|
|
7
|
+
# @celigo/api-specs
|
|
8
|
+
|
|
9
|
+
OpenAPI 3.2 specifications for the [Celigo integrator.io](https://www.celigo.com) REST API,
|
|
10
|
+
packaged as files for tooling. They are the documents behind the
|
|
5
11
|
[API reference on the Celigo Developer Platform](https://developer.celigo.com/api/api-reference),
|
|
6
12
|
and what the [Celigo CLI](https://developer.celigo.com/cli) validates resource documents against.
|
|
7
13
|
|
|
8
|
-
|
|
9
|
-
|
|
14
|
+
```bash
|
|
15
|
+
npm install @celigo/api-specs
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## What's in the package
|
|
19
|
+
|
|
20
|
+
Every platform resource has its own OpenAPI document under `dist/` — connections, flows, exports,
|
|
21
|
+
imports, integrations, jobs, scripts, tools, and the rest. Each file is self-contained, with every
|
|
22
|
+
`$ref` already inlined, so it can go straight into a client generator, a request validator, or an
|
|
23
|
+
AI agent's context with no loader configuration.
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
dist/connection.yml
|
|
27
|
+
dist/flow.yml
|
|
28
|
+
dist/export.yml
|
|
29
|
+
dist/import.yml
|
|
30
|
+
...
|
|
31
|
+
schemas.json
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
`schemas.json` is the schema pack that the Celigo CLI's `celigo lint` command validates documents
|
|
35
|
+
against, compiled from the same bundles. Other consumers can ignore it.
|
|
36
|
+
|
|
37
|
+
Resolve a document the same way as any other packaged file:
|
|
38
|
+
|
|
39
|
+
```js
|
|
40
|
+
import { createRequire } from "node:module";
|
|
41
|
+
|
|
42
|
+
const require = createRequire(import.meta.url);
|
|
43
|
+
const specPath = require.resolve("@celigo/api-specs/dist/connection.yml");
|
|
44
|
+
```
|
|
10
45
|
|
|
11
46
|
## The API these specs describe
|
|
12
47
|
|
|
@@ -23,97 +58,51 @@ The API is served from four regional hosts. Use the one your account lives in:
|
|
|
23
58
|
| AU | `https://api.au.integrator.io` |
|
|
24
59
|
| CA | `https://api.ca.integrator.io` |
|
|
25
60
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
[developer.celigo.com/api/api-reference](https://developer.celigo.com/api/api-reference). Each
|
|
30
|
-
resource has its own page, with a console for trying calls against your own account.
|
|
31
|
-
|
|
32
|
-
To consume the specs as files — client generation, request validation, or grounding an AI agent on
|
|
33
|
-
the API surface — install the published bundles:
|
|
34
|
-
|
|
35
|
-
```bash
|
|
36
|
-
npm install @celigo/api-specs
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
Jenkins publishes the package with `schemas.json` at the package root for `celigo lint` and the
|
|
40
|
-
bundled OpenAPI documents under `dist/` for other consumers. The tarball excludes the authored
|
|
41
|
-
`specs/` tree, tests, scripts, internal operations, deprecated fields, and source-only metadata.
|
|
42
|
-
|
|
43
|
-
Each resource ships as one self-contained OpenAPI 3.2 document with every `$ref` already inlined,
|
|
44
|
-
so a spec file can go straight to a generator or validator with no loader configuration.
|
|
61
|
+
To browse the API interactively, use the
|
|
62
|
+
[rendered reference](https://developer.celigo.com/api/api-reference): each resource has its own
|
|
63
|
+
page, with a console for trying calls against your own account.
|
|
45
64
|
|
|
46
65
|
## What the specs cover
|
|
47
66
|
|
|
48
67
|
The specs are prescriptive. They describe the API surface Celigo supports and intends to keep
|
|
49
68
|
supporting — not everything the server happens to tolerate. Internal endpoints, deprecated fields,
|
|
50
|
-
and retired enum values are deliberately left out
|
|
69
|
+
and retired enum values are deliberately left out.
|
|
51
70
|
|
|
52
71
|
The practical consequence: a request that validates against these specs is one you can build on.
|
|
53
|
-
The reverse does not hold. The
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
Alongside standard OpenAPI, the specs carry `x-` extensions that Celigo tooling reads —
|
|
57
|
-
`x-enumDescriptions` explains what each enum value does, `x-celigo-refModel` names the resource an
|
|
58
|
-
ID field points at, and a handful of others. Standard OpenAPI consumers can ignore them;
|
|
59
|
-
[CONTRIBUTING.md](CONTRIBUTING.md) documents what each one means.
|
|
60
|
-
|
|
61
|
-
## Repository layout
|
|
62
|
-
|
|
63
|
-
Specs are authored as multi-file `$ref` trees and bundled into the single-file documents that get
|
|
64
|
-
published.
|
|
72
|
+
The reverse does not hold. The server may accept a payload no spec describes, and that payload may
|
|
73
|
+
be ignored or rejected later.
|
|
65
74
|
|
|
66
|
-
|
|
67
|
-
specs/v1/ authored source, one directory per resource
|
|
68
|
-
common/ schemas and responses shared across specs
|
|
69
|
-
connection/
|
|
70
|
-
connection.yml spec root: info, servers, security, path refs
|
|
71
|
-
paths/*.yml path item objects
|
|
72
|
-
components/schemas/ request and response schemas
|
|
73
|
-
flow/
|
|
74
|
-
...
|
|
75
|
-
redocly.yaml spec registry, lint rules, and publish decorators
|
|
76
|
-
scripts/ bundling, validation gates, and publishing
|
|
77
|
-
tests/live/ contract tests that exercise the specs against the live API
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
`specs/v1/` mirrors the `/v1/` URL prefix. A future breaking version would land in a sibling
|
|
81
|
-
`specs/v2/` tree; additive v2 endpoints go straight into the existing spec files.
|
|
82
|
-
|
|
83
|
-
## Development
|
|
75
|
+
## Extensions
|
|
84
76
|
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
npm run lint # Redocly lint across every registered spec
|
|
88
|
-
npm run bundle # validation gates, then bundle to dist/
|
|
89
|
-
```
|
|
77
|
+
Alongside standard OpenAPI, the documents carry `x-` extensions that Celigo tooling reads. Standard
|
|
78
|
+
OpenAPI consumers can ignore them; validators and AI agents may find them useful.
|
|
90
79
|
|
|
91
|
-
|
|
92
|
-
|
|
80
|
+
| Extension | Where | Meaning |
|
|
81
|
+
| ------------------------------ | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
82
|
+
| `x-enumDescriptions` | Fields with `enum` | One line per enum value explaining what it does. |
|
|
83
|
+
| `x-celigo-refModel` | ID fields | The resource type the ID points at (`flows`, `scripts`, and so on). |
|
|
84
|
+
| `x-celigo-ai-guidance` | Schemas and fields | Operational hints for AI agents: which default to choose, what to set when scaffolding, and the concrete failure that results from getting it wrong. |
|
|
85
|
+
| `x-celigo-ui-override` | Schemas and fields | Marks a requirement or default that mirrors the integrator.io form, which is stricter than the raw API, so generated configurations are complete and connectable. |
|
|
86
|
+
| `x-celigo-agent` | Expression fields | How the field is authored — capability tags such as `handlebars`, `sql`, `graphql`, `filter`, `mapping`, `script`. |
|
|
87
|
+
| `x-celigo-handlebars-context` | Handlebars fields | The data context the expression is evaluated against, such as `pre-mapped` or `post-mapped`. |
|
|
88
|
+
| `x-celigo-excludeAdaptorTypes` | Shared adaptor fields | Adaptor types the field does not apply to. |
|
|
89
|
+
| `x-lowercase`, `x-uppercase` | String fields | The API normalizes the value's case on save. |
|
|
93
90
|
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
[tests/live/README.md](tests/live/README.md) covers the contract test suite.
|
|
91
|
+
`x-internal`, `x-enable-proxy`, and `x-displayName` control the documentation toolchain and carry no
|
|
92
|
+
API meaning.
|
|
97
93
|
|
|
98
94
|
## Support
|
|
99
95
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
96
|
+
For a problem with the specs — a schema that disagrees with the API, a missing field or endpoint, a
|
|
97
|
+
description that led you somewhere wrong — or with integrator.io itself, contact
|
|
98
|
+
[Celigo Support](https://docs.celigo.com/hc/en-us/requests/new). The most useful report names the
|
|
99
|
+
spec and operation, shows the request you made, and shows what the API returned next to what the
|
|
100
|
+
spec said it would. Never include API tokens, credentials, or customer data.
|
|
104
101
|
|
|
105
|
-
Report a suspected vulnerability
|
|
106
|
-
|
|
107
|
-
[Celigo Support](https://docs.celigo.com/hc/en-us/requests/new). Never include tokens,
|
|
108
|
-
credentials, or customer data.
|
|
102
|
+
Report a suspected security vulnerability through the same channel, privately, with the spec and
|
|
103
|
+
operation involved, what it discloses or enables, and reproduction steps.
|
|
109
104
|
|
|
110
105
|
## License
|
|
111
106
|
|
|
112
|
-
MIT
|
|
113
|
-
governed by your Celigo agreement.
|
|
114
|
-
|
|
115
|
-
## Contributing
|
|
116
|
-
|
|
117
|
-
[CONTRIBUTING.md](CONTRIBUTING.md) has the authoring rules and how publishing works.
|
|
118
|
-
Participation follows [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md); [SECURITY.md](SECURITY.md) and
|
|
119
|
-
[SUPPORT.md](SUPPORT.md) carry the full policies.
|
|
107
|
+
MIT. The `LICENSE` file ships in the package. The specs describe the integrator.io API; use of the
|
|
108
|
+
API itself is governed by your Celigo agreement.
|
package/dist/integration.yml
CHANGED
|
@@ -1474,6 +1474,24 @@ paths:
|
|
|
1474
1474
|
description: |-
|
|
1475
1475
|
Removes a connection's registration from the integration. This does not delete the connection
|
|
1476
1476
|
itself -- it only removes it from the integration's registered-connections list.
|
|
1477
|
+
|
|
1478
|
+
Fails while any resource in the integration still uses the connection -- a step
|
|
1479
|
+
(export, import, or lookup) in one of its flows, Tools, or APIs bound to it through
|
|
1480
|
+
`_connectionId`, or an alias on the integration or one of its flows whose
|
|
1481
|
+
`_connectionId` points at it. Move the steps to another connection first (a whole flow
|
|
1482
|
+
at once with `PUT /v1/flows/{_id}/replaceConnection`; Tool and API steps through their
|
|
1483
|
+
own step-level `replaceConnection`), remove any alias that still points at it, then
|
|
1484
|
+
unregister.
|
|
1485
|
+
x-celigo-ai-guidance:
|
|
1486
|
+
- |-
|
|
1487
|
+
Before calling, list what the integration still binds to this connection: the
|
|
1488
|
+
`_connectionId` of every export and import in the integration
|
|
1489
|
+
(`GET /v1/integrations/{_id}/exports` and `/imports` cover flow, Tool, and API
|
|
1490
|
+
steps) and every `aliases[]._connectionId` on the integration and its flows. While
|
|
1491
|
+
any remain the platform returns 400 `not_allowed` ("The connection is being actively
|
|
1492
|
+
used by the integration. Please ensure no integration resource is using the
|
|
1493
|
+
connection before deregistering."). `replaceConnection` moves steps; it does not
|
|
1494
|
+
rewrite aliases -- update the `aliases` array on the integration or flow.
|
|
1477
1495
|
parameters:
|
|
1478
1496
|
- name: _id
|
|
1479
1497
|
in: path
|
|
@@ -1498,6 +1516,21 @@ paths:
|
|
|
1498
1516
|
responses:
|
|
1499
1517
|
'204':
|
|
1500
1518
|
description: Connection unregistered successfully. No body returned.
|
|
1519
|
+
'400':
|
|
1520
|
+
description: |-
|
|
1521
|
+
A resource in the integration still uses the connection -- a flow, Tool, or API
|
|
1522
|
+
step bound to it, or an alias on the integration or one of its flows that points at
|
|
1523
|
+
it. Error code: `not_allowed`.
|
|
1524
|
+
content:
|
|
1525
|
+
application/json:
|
|
1526
|
+
schema:
|
|
1527
|
+
$ref: '#/components/schemas/Error'
|
|
1528
|
+
examples:
|
|
1529
|
+
in_use:
|
|
1530
|
+
value:
|
|
1531
|
+
errors:
|
|
1532
|
+
- code: not_allowed
|
|
1533
|
+
message: The connection is being actively used by the integration. Please ensure no integration resource is using the connection before deregistering.
|
|
1501
1534
|
'401':
|
|
1502
1535
|
$ref: '#/components/responses/401-unauthorized'
|
|
1503
1536
|
'404':
|
package/package.json
CHANGED
|
@@ -1,8 +1,16 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@celigo/api-specs",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.13",
|
|
4
4
|
"private": false,
|
|
5
5
|
"description": "Public OpenAPI bundles (dist/) and the celigo-cli lint schema pack (schemas.json).",
|
|
6
|
+
"keywords": [
|
|
7
|
+
"openapi",
|
|
8
|
+
"openapi3",
|
|
9
|
+
"celigo",
|
|
10
|
+
"integrator.io",
|
|
11
|
+
"api",
|
|
12
|
+
"specs"
|
|
13
|
+
],
|
|
6
14
|
"files": [
|
|
7
15
|
"dist/",
|
|
8
16
|
"schemas.json"
|
|
@@ -15,6 +23,10 @@
|
|
|
15
23
|
"type": "git",
|
|
16
24
|
"url": "https://github.com/celigo/integrator-api-specs.git"
|
|
17
25
|
},
|
|
26
|
+
"homepage": "https://developer.celigo.com/api/api-reference",
|
|
27
|
+
"bugs": {
|
|
28
|
+
"url": "https://docs.celigo.com/hc/en-us/requests/new"
|
|
29
|
+
},
|
|
18
30
|
"license": "MIT",
|
|
19
31
|
"scripts": {
|
|
20
32
|
"lint": "redocly lint",
|