Versioning and changes
The /api/v1 compatibility promise - additive changes only, nothing removed that a client reads - how breaking changes are caught, and where to see changes.
In short
Code you write against the BuildBase API today keeps working. BuildBase adds new things - new routes, new fields, new error codes - but does not rename, remove or change the meaning of what is already there. Every version of the SDK that customers have installed is still calling the server, so a removal would break real apps, and the rules below exist to stop one.
The promise on /api/v1
| BuildBase may | BuildBase does not |
|---|---|
| Add a route | Remove or rename a route |
| Add a field to a response | Remove, rename or retype a response field that a published SDK reads |
| Add an optional request field, with a default | Make a new field required, or require a new header |
Add an error code, or a value to a list of values | Rename an error code, or change the status an existing refusal answers with |
Add page and limit to a list, opt-in | Start paging a list by default, so the first page looks like everything |
| Add a webhook event, or fields to its payload | Rename or remove an event, or remove a payload field |
The version in the path, v1, is the compatibility line. There is no version header to send.
What to build on
To stay safe as the API grows:
- Ignore fields you do not know. A response gains fields over time.
- Accept values you do not know in a
statusorcode, and treat them as the general case. - Branch on
codeand the status, never on the text ofmessage, which can be reworded. - Keep the envelope you see. A route that answers a bare object keeps doing so; one that answers
{ "success": true, "data": ... }keeps that (HTTP API errors).
How a breaking change is caught
Before a change reaches the server, it is checked against the contract:
- The OpenAPI document is generated from the server's own routes on every change, and CI fails when the committed spec no longer matches the code.
- A breaking-change check compares the new spec with the one on the main branch. A change that removes or narrows something callers rely on fails, unless the people responsible for the API decide on purpose to accept it and mark the pull request so.
- The review rules for every route the SDK calls ask who reads a field before it is touched, in the current SDK and its older versions.
Retiring something is a human decision. What is retired keeps working first: it is marked deprecated in the docs and the SDK, its use is watched, and it is removed only once the remaining callers are known.
Where to see what changed
- The changelog, https://www.buildbase.app
/changelog, with an RSS feed at/changelog/feed.xml: features and fixes as they ship, API changes among them. - The spec itself.
info.versionin the OpenAPI document names its version. Diff two downloads to see every operation added. - The SDK's release notes on npm, https://www.npmjs.com/package/@buildbase/sdk, for the TypeScript side.
curl -s "https://docs.buildbase.app/openapi/public-v1.json" | jq '.info.version'Next steps
- The OpenAPI spec - download it and diff it.
- HTTP API errors - the shapes your code relies on.
- Error codes - codes are only ever added.