Publish and lifecycle
Draft, publish, deprecate, retire. Publishing registers gateway routes and freezes the OpenAPI contract.
Lifecycle: draft → published → deprecated → retired.
Publishing an API or webhook with spec.ingress:
- Sets lifecycle published and stores an OpenAPI snapshot (
GET /api/v1/catalog/{id}/openapi) - Applies APISIX routes (reference stack)
- Auto-deprecates the previous published version (default) and removes its edge routes
- Sets sunset on the superseded version (default 90 days) — after sunset, a daily job retires it
Versioning
- Patch/minor (same major): same ingress paths — edge, policies, and docs change; backend code unchanged unless you deploy platform
- Major: new ingress paths required (e.g.
/api/v1/...→/api/v2/...) andspec.implementationRefpointing at the new handler
GitOps
Production catalog lives in catalog/prod/ in the Connect repo and is mounted into the platform. Changes require commit + deploy.
Who can write
Operators create and publish. Admins deprecate and retire (optional sunset). Developers read published OpenAPI. Operators register consumers and grants on Portal Consumers.
Try it
APIs → System → Catalog (SSO in production). Published contracts use the catalog snapshot, not live springdoc.
If this fails
| Symptom | Cause |
|---|---|
| Publish 5xx | APISIX Admin down while provider is apisix |
| Route missing at the edge | Artifact has no spec.ingress, or publish did not apply |
| Major publish rejected | Same ingress paths as previous published major |
| Deprecated still callable | Sunset not reached yet; internal platform path may still respond until code removed |
| Two published versions | Auto-deprecate disabled (connect.catalog.auto-deprecate-on-publish=false) |