How versioning works in the Sally API
The version of the Sally API is the first path segment: /v1.0. There is deliberately no sliding /v1, so a path you wrote down keeps meaning what it meant. This page explains what freezing a version means and which changes get a new version.
Quick navigation
- The current version
- What freezing means
- What does not get a new version
- The exception: the health check
1. The current version
| Version | Status | Path |
|---|---|---|
1.0 | Current, under active development, not frozen yet | /v1.0 |
Version 1.0 can still change in ways that break a client, so treat it as a moving target for now. Every change is listed in the release notes. We will announce when the version is frozen.
2. What freezing means
Once a version is frozen, it keeps answering exactly as it did at that moment and is never changed again. Work continues on the next version (/v1.1), and a client that wants the old behavior simply stays on its path. A redesign too large to carry that way becomes a new major version (/v2).
3. What does not get a new version
A new version is only created for a change that could break a client. A purely additive change does not get one: a new endpoint, a new field or a new enum value appears in the version you are already using.
Your client therefore has to tolerate two things: fields it does not know and enum values it has never seen. A parser that rejects either of them breaks on a change that was designed to be harmless.
4. The exception: the health check
GET /health deliberately carries no version. A liveness probe says nothing about the contract, and a monitor should not have to follow a version change.