n8n:public-api

Source excerpt starting at line 1.

1# Public API v1 — reference2 3Detail for tasks that need it. Essentials and the rule tiers are in4[SKILL.md](SKILL.md). Open the cited files; they are the source of truth.5 6## List endpoints and cursor pagination7 8The internal API mixes cursor- and page-based pagination. New Public API list9endpoints use **cursor-based** pagination — do not copy an internal controller's10model.11 12Copy the working flow from `v1/controllers/tags.public.controller.ts` (and13`workflows.public.controller.ts` for a `@Param` list) rather than pasting a14snippet here — a copy would drift. The moving parts:15 16- Input DTO takes `limit: publicApiPaginationSchema.limit` plus an opaque17  `cursor: z.string().optional()` — cherry-pick `limit` but never spread the whole18  `publicApiPaginationSchema`. That schema also exports `offset`, used by19  internal-API-style page params elsewhere; a Public API list DTO must never20  expose it as a query param. See `ListTagsQueryDto` for the shape to copy.21- `decodeCursor` / `encodeNextCursor` live in22  `v1/shared/services/pagination.service.ts`. Decode the incoming cursor to23  `{ offset, limit }`, guard the decoded shape, and pass `offset`/`limit` to the24  service — never `{ skip, take }`. `offset` is an internal implementation25  detail of the cursor here, never a client-facing query param. TypeORM's26  `skip`/`take` stay inside the repository, at the `find` call.27- Treat the cursor as opaque; never hand-encode a token.28- Return an envelope `{ data, nextCursor }` — never a bare array.29- `encodeNextCursor(...)` returns `null` when there is no further page; surface30  that as `nextCursor: null`.31- An invalid/undecodable cursor is a `400` via the existing bad-request error.32- For an existing list endpoint, keep its current *cursor* semantics unchanged.33  A leaked `offset` query param (DTO spreading `publicApiPaginationSchema`34  instead of picking `limit`) is a defect to remove, not a contract to35  preserve — decorator-routed DTOs validate via a plain `z.object()`, which36  silently strips unknown query keys rather than rejecting them, so removing37  `offset` from the DTO makes it inert rather than erroring for existing38  callers.39 40The output DTO wraps the list as `{ data, nextCursor }` and is declared with41`@ApiResponse(...)` so the registry strips undeclared fields.42 43## Updates and write-only secrets44 45- Default to `PUT`. The update DTO describes the full mutable object; the46  validation layer rejects a partial payload (typically `400`). Don't implement47  merge semantics behind a `PUT`.48- Don't add a new `PATCH` unless the task explicitly requires partial-update49  semantics or an established resource-specific exception applies.50- Migrating an update endpoint keeps its current public HTTP semantics.51 52Write-only secrets (credentials, tokens, keys) support GET→PUT round-trip via a53resource-specific sentinel/placeholder (e.g. credentials use54`CREDENTIAL_BLANKING_VALUE` / related helpers — do not invent a new format):55 56- `GET` never returns the real secret; it returns that sentinel (or omits the57  field). Never echo a real secret in responses or error details (including58  test-connection and upstream error messages).59- On `PUT`, sending the **exact** sentinel from `GET` means **keep** the stored60  secret. Sending **any other** value means **replace** it. Do not treat61  "looks masked" or "field omitted" as keep unless the resource helper/tests say62  so.63- Reuse the resource's redact/unredact (or equivalent) helper in the service —64  don't reimplement sentinel detection or credential merge in the controller, and65  never persist the sentinel as a real secret.66- Sentinel support does not make the whole `PUT` a partial update; other required67  client-manageable fields stay required. Server-managed/immutable fields from68  `GET` (`id`, timestamps, …) follow the resource DTO (ignored or not required on69  write).70 71## Test-before-save endpoints72 73A connection/config-test endpoint validates the config in the **request body**,74not stored state — unless the endpoint explicitly verifies an already-saved75resource. Secret handling is the same as any other endpoint — see above.76 77## Errors78 79- Don't leak persistence errors, stack traces, or internal messages. Reuse80  existing domain errors when the registry already maps them to the right public81  errors; otherwise map at the controller boundary.82- Follow the error semantics of the nearest existing public controller; invalid83  input and invalid cursors use the existing bad-request pattern.84- When migrating, preserve the documented status codes and public error behavior.85 86## Testing matrix87 88Always (in SKILL.md): happy path, input-validation failure, missing API-key89scope, RBAC denial. Add whichever apply, matching the nearest existing tests:90 91- At least one integration test under `packages/cli/test/integration/public-api/`92  that exercises the real service/DB path for the main success case (and93  paging/RBAC where they matter). Controller unit tests with a mocked service are94  fine for wiring/validation edges — not as the only coverage of behavior.95- Cursor paging: first page, final page with `nextCursor: null`, invalid cursor,96  `limit` handling.97- Not-found and conflict semantics.98- Response carries no sensitive/internal fields.99- Credential resources: response has no real secret (sentinel or omitted);100  `PUT` with the exact sentinel keeps the secret; any other value replaces it;101  the sentinel is never persisted as a real secret.102- Migration: path, method, status codes, scope, and response contract are103  unchanged. Tests alone cannot show this — see104  [Verifying a migration](#verifying-a-migration).105 106## Migrating legacy EOV endpoints107 108Legacy `express-openapi-validator` endpoints live under109`v1/handlers/`, wired through `openapi.yml` with `x-eov-operation-*` and request110types in `packages/cli/src/public-api/types.ts`. Treat these as migration targets,111not templates.112 113- Prefer migrating to `@PublicApiController` over extending the handler.114- Preserve the public contract: path, method, scopes, status codes, response115  shape, and pagination.116- Move HTTP concerns into the controller and business orchestration into the117  shared service; keep the controller a thin HTTP boundary. If the legacy118  handler was itself already just a thin wrapper around an internal119  `@RestController` (calling its methods directly, e.g.120  `Container.get(SomeController).createThing(req, res, payload)`), the new121  public controller can call that same internal controller directly — no need122  to duplicate its validation/business logic.123- A route must be served by either the EOV handler or a controller, not both —124  the build's `mergeDecoratorDocument` (`v1/openapi-gen/generate.ts`) throws on125  a path+method declared by both sides. Remove the legacy wiring (its path's126  `$ref` entry in `openapi.yml`, the `x-eov-operation-*` handler, and its127  `handler.ts`) only after the new controller is registered, `pnpm build`128  regenerates the spec cleanly, and tests are updated.129- Fully delete the migrated legacy files: the handler's `.ts`, its130	`spec/paths/*.yml` and `spec/schemas/*.yml`, and any now-dead request type131	in `packages/cli/src/public-api/types.ts`. Then check132  `v1/shared/spec/schemas/_index.yml` and `v1/shared/spec/parameters/_index.yml`133  for entries that `$ref` one of the deleted schema/parameter files — those are134  separate from the path's own `$ref` in `openapi.yml` and are easy to miss;135  left dangling, the next bundle fails on a broken `$ref`.136- If the legacy handler gated on a license (`isLicensed('feat:x')` middleware),137  `@Licensed('feat:x')` now replicates that for a controller route (see the138  decorator table in [SKILL.md](SKILL.md#declaring-a-controller)) — but only for139  a single feature. If the legacy check was an any-of/all-of over several flags140  (e.g. `LicenseState.isProvisioningLicensed()`), `@Licensed` can't express141  that; replicate it manually in the controller instead, don't drop it - this142  is exactly what the internal `provisioning.controller.ee.ts` and143  `role-mapping-rule.controller.ee.ts` already do, since neither uses144  `@Licensed` for that reason.145- As a legacy file drops repository access / the `export =` tuple, remove its146  entry from the `off` allowlists for `no-repository-in-public-api-handler` and147  `require-public-api-controller` in `packages/cli/eslint.config.mjs` (shrink-only148  — never extend them).149- For complex legacy-only, multipart, or non-standard endpoints, study the150  nearest existing handler first.151- Keep each field in its original position when you extract a request shape shared152  by two routes, and destructure out the ones a route doesn't take. The generator153  emits properties in shape order, so a moved field rewrites the `*.generated.yml`154  of a route the PR wasn't changing.155 156## Verifying a migration157 158Tests are written against the new code, so they can't show that the old behavior159survived. These checks can:160 161- Diff live responses against master. Run the route on an instance per branch and162  compare status, body, and error message for the same requests. Reading the old163  YAML beside the new Zod schema doesn't find the differences.164- Check whether a field is absent or `null`. `activeVersion` omitted is not the165  same response as `activeVersion: null`; use a conditional spread to omit it.166- Check query-param coercion at the edges (`""`, `"0"`, `"false"`, absent). A Zod167  DTO and the old validator don't coerce identically.168- Request a route the PR didn't migrate. A shared DTO change can stop the spec169  bundle compiling at startup, which turns every legacy route into a `500` without170  failing a test.171 172## CI and merging173 174Two failures that a migration hits outside the code itself:175 176- Merge master in before merging. A generator change on master leaves every177  branch's committed `*.generated.yml` stale, and `generated-spec-drift.test.ts`178  then fails only on the merge commit, so the PR itself stays green and179  `MERGEABLE`. `gh pr checks` hides `merge_group` runs; look for the run on180  `gh-readonly-queue/master/pr-<number>-<sha>`.181- Ask a maintainer for a `/size-limit-override` early. Generated YAML counts182  toward the 1,000-line PR size limit, so a single-route migration can exceed it183  on generator output alone.184