# 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 `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](/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

- **The changelog**, [https://www.buildbase.app](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.version` in [the OpenAPI document](/http-api/openapi) 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](https://www.npmjs.com/package/@buildbase/sdk), for the TypeScript side.

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

## Next steps

- [The OpenAPI spec](/http-api/openapi) - download it and diff it.
- [HTTP API errors](/http-api/errors) - the shapes your code relies on.
- [Error codes](/reference/error-codes) - codes are only ever added.
