OpenAPI Specification

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.

Choosing What to Expose

Exposure is a deliberate choice per datastore. Nothing is exposed merely because it exists.

Where to find it

Architect Panel → Integration & Connections:

• API Server — which datastores are exposed, and the API settings
• API Clients — per-client credentials and their rights

Start from the use case, not the schema

Expose what a specific consumer needs for a specific purpose. Exposing broadly "in case something is useful" produces a wide surface, and every field on it is a field somebody may come to depend on — which then makes it hard to change.

The narrower the exposure, the more freedom you keep to restructure your own data later.

Permissions still apply

The API enforces the same permission model as the interface. A client sees what its credentials allow, and row-level and field-level rules apply exactly as they do for a person.

Exposing a datastore is not the same as making its contents public — but it is the step that makes a permissions mistake reachable from outside, so it is worth re-checking the permissions on anything you expose.

Some subsystems can never be exposed

Certain internal areas are excluded from exposure by design and the exclusion is not configurable. Messaging is the clearest example: those tables carry message content, recipient identity and delivery detail, and there is no version of exposing them through a generic API that is a good idea.

If you find you cannot expose something, that is usually why, and the answer is to build a purpose-shaped endpoint rather than to look for a way round it.

Fields deserve the same thought as datastores

A datastore worth exposing may contain fields that are not. Internal notes are the usual culprit — free text written by staff for colleagues, in a tone and with a candour nobody chose with an external audience in mind.

Review the field list, not just the datastore list, before enabling anything.

One client, one purpose

Issue a client per consumer and per purpose in API Clients. Shared credentials cannot be revoked without collateral damage, and their call logs cannot tell you who did what.

Worked example

A housing association exposes a repairs datastore to its contractor's system. Three fields are excluded: the internal notes, the vulnerability flag, and the officer's mobile number. The contractor gets what it needs to schedule work and nothing it does not, and the exclusion decisions are recorded so the next person to look does not simply re-enable them.

Review it periodically

Exposure decisions get made for a project and then persist long after the project ends. Once a year, look at what is exposed and to whom, and remove what nothing is using. An unused exposed datastore is risk carrying no benefit.

Recommendations

• Expose the minimum, and review the field list too.
• Re-check permissions on anything you expose — exposure makes mistakes reachable.
• One client per consumer.
• Annual review, and revoke what is dormant.