Generating an OpenAPI Specification
OpenAPI is the standard way to describe a REST API in machine-readable form. The platform generates one from your own configuration rather than asking anybody to write it.
Where to find it
Architect Panel → Integration & Connections:
- OpenAPI Specification — generate, preview and download the spec
- API Server — the API itself, and which datastores it exposes
- API Clients — who may call it, and with what rights
Why generate rather than write
A hand-written specification is accurate on the day it is written and diverges from then on. A generated one reflects what the API actually exposes today, which is what a consumer needs — and it cannot drift, because there is nothing separate to keep in step.
What a consumer gets
- Client libraries generated in their own language, rather than hand-rolled HTTP calls.
- Request and response validation before anything is sent.
- Interactive documentation and test tooling that works without anybody reading prose.
For an integration partner this is often the difference between a day of work and a fortnight, and it removes an entire category of "the docs said the field was a string" conversations.
It only describes what you exposed
The generator works from the datastores marked as exposed on the API Server, so the specification is a description of a decision you already made rather than a new exposure. If something is missing from the spec, the question to ask is whether it should be exposed at all — not how to add it to the document.
Regenerate after changes
Add a field, add a datastore, change a type, and the specification is out of date until regenerated. Make regeneration part of your release routine and hand consumers the new file when the API changes, rather than letting them discover the difference at runtime.
Versioning is a contract
Consumers build against a version of your specification. Adding a field is safe — well-built clients ignore what they do not recognise. Removing a field, renaming one, or changing a type breaks them, usually silently and usually in production.
Treat the published specification as a contract: add freely, change carefully, remove only with notice and a deprecation period. If you must break something, version the endpoint rather than mutating it.
Worked example
A council exposes a licensing datastore to a partner who runs the public search site. The partner generates a client from the spec in an afternoon. When a new field is added six months later, the council regenerates and sends the file; the partner's client keeps working untouched because nothing was removed or renamed.
Recommendations
- Regenerate and publish on every release that touches an exposed datastore.
- Give consumers the file, do not make them scrape it.
- Never remove a field without notice. Deprecate, wait, then remove.
- Keep old versions available for as long as anyone builds against them.