Skip to content
BuildBase
HTTP API menu

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 mayBuildBase does not
Add a routeRemove or rename a route
Add a field to a responseRemove, rename or retype a response field that a published SDK reads
Add an optional request field, with a defaultMake a new field required, or require a new header
Add an error code, or a value to a list of valuesRename an error code, or change the status an existing refusal answers with
Add page and limit to a list, opt-inStart paging a list by default, so the first page looks like everything
Add a webhook event, or fields to its payloadRename 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 status or code, and treat them as the general case.
  • Branch on code and the status, never on the text of message, 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:

  1. 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.
  2. 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.
  3. 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

curl -s "https://docs.buildbase.app/openapi/public-v1.json" | jq '.info.version'

Next steps