This page states what you can rely on when you build against the OutBIG API, and what happens if that ever changes. It is a commitment, not a description of intent — the point of writing it down is that you can plan against it.
The version is in the path: /api/v1. There is no version header and no content-type negotiation for versions — the address you call is the contract you get.
A breaking change gets a new path (/api/v2). /api/v1 will not change shape underneath you.
Removing an endpoint, a field or a response code. Renaming a field. Changing the type or the unit of a field. Narrowing what a parameter accepts. Adding a required parameter.
Changing the meaning of an existing value counts too, even when the type stays the same — for example if amountCents ever stopped being cents.
Adding an endpoint, a field, an optional parameter or a new value to an existing enumeration. Wording of message and hint in error responses — branch on error.code, which is stable.
**Ignore fields you do not know rather than failing on them.** A client that rejects unexpected fields will break on an additive change, and additive changes are the ones we make most often.
If /api/v1 is ever retired, every response from it will carry the Deprecation and Sunset headers (RFC 8594) for **at least 6 months** before it stops answering, and this page will name the date.
Until that happens, those headers are not sent. A Deprecation header on a version that is not deprecated would be a false statement about the current state, and we would rather fail an automated readiness check than make one.
The Sunset header carries the date the endpoint stops answering. Deprecation carries the date the deprecation took effect. Both are HTTP dates, in UTC.
In the response headers, on this page, and in /llms.txt. There is no mailing list — the API needs no account, so there is no address to write to.
If you rely on this API and want to be told directly, say so at office@ostheimer.at and you will be.