API reference
Versions and compatibility
How the API is versioned, and how it stays compatible with workbenches already in use.
Versioned paths
Every public route has its version in its path: /auth/v1, /cloud/v1, /platform/v1, /relay/v1, /ingest/v1, /catalogue/v1, /policy/v1. This reference describes version 1 of each.
Versioned documents
Some bodies also carry a version of their own:
| Document | Field | Current |
|---|---|---|
| Discovery document | version | 1 |
| Ingest envelope | schemaVersion | 1 |
| Catalogue | version | 1 |
Staying compatible
Workbenches already installed must keep working when the platform is updated, so the API changes in ways old clients can ignore:
- New fields are optional, and clients ignore fields they do not know.
- New catalogue kinds (tool servers and document templates) are only sent to a client that asks for them with
?include=, because older workbenches know a fixed list of kinds. - New features are announced in the discovery document's
capabilitiesandedition, so a client can tell what a platform offers before using it.
The version of a running platform is in GET /healthz.