OpenAPI Specification
Generate a machine-readable API specification from the datastores you have chosen to expose.
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.
Where to find it
Architect Panel → Integration & Connections:
- OpenAPI Specification — generate and download the spec
- API Server — the API itself and its settings
- 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. A generated one reflects what the API actually exposes, which is what a consumer needs. It also cannot drift, because there is nothing to keep in step.
What a consumer gets
Client libraries generated in their own language, request validation, and API tooling that works without anyone reading prose. For an integration partner this is the difference between a day and a fortnight.
It only describes what you exposed
The generator works from the datastores marked as exposed, 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 is whether it should be exposed at all.
Regenerate after changes
Add a field or a datastore and the specification is out of date until regenerated. Make it part of your release routine, and hand consumers the new spec when the API changes rather than letting them discover it.
Versioning
Consumers build against a version. Removing a field or changing a type breaks them silently, and they will find out in production. Treat the published specification as a contract: add freely, change carefully, remove only with notice.
Choosing What to Expose
Exposure is a deliberate choice per datastore. Nothing is exposed because it exists.
Where to find it
Architect Panel → Integration & Connections:
- API Server — which datastores are exposed
- API Clients — per-client credentials and rights
Start from the use case
Expose what a specific consumer needs for a specific purpose, rather than exposing broadly in case something is useful. A wide API is a wide surface, and every field on it is a field somebody may come to depend on.
Permissions still apply
The API enforces the same permission model as the interface. A client sees what its credentials allow, and exposure does not bypass row-level or field-level rules. Exposing a datastore is not the same as making its contents public.
Some prefixes are never exposed
Certain internal subsystems are excluded from exposure by design — messaging is one, because those tables carry message content and recipient identity. That exclusion is not configurable, and it is deliberate.
Fields deserve the same thought
A datastore worth exposing may contain fields that are not. Notes fields are the usual culprit: free text written by staff for internal purposes, which nobody was writing with an external audience in mind.
Review it periodically
Exposure decisions get made for a project and then persist. Once a year, look at what is exposed and to whom, and remove what nothing is using. An unused exposed datastore is risk without benefit.