Versioning
The v1 stability promise, deprecation headers and sunsets.
The v1 promise
https://fomodata.dev/v1 is stable. Every public endpoint is versioned in the path; there are no unversioned public endpoints. Breaking changes require /v2, unless a critical security issue leaves no alternative, and then we say so in the changelog the same day.
What can change in v1
Additive, backwards-compatible changes ship without a new version. Write clients that tolerate them:
- New endpoints, new optional request parameters and new optional body fields.
- New fields on response objects. Ignore fields you don't know.
- New event types. Webhooks and streams only send types you subscribed to, but handle unknown types gracefully.
- New error codes within existing types, and changes to human-readable messages.
- New values in enums documented as open, such as verification
reason.
What counts as breaking
- Removing or renaming an endpoint, field, parameter or event type.
- Changing a field's type or meaning, or making an optional parameter required.
- Changing id formats, pagination semantics, error codes for existing conditions, or webhook signature format.
Deprecation and sunset
We never silently break the API. When something in v1 is deprecated, it keeps working until its sunset date, and you're told four ways:
| Signal | Where |
|---|---|
Deprecation: true | Response header on every call to the deprecated operation. |
Sunset: <HTTP date> | Response header with the date it stops working. |
Link: <guide>; rel="deprecation" | Response header pointing to the migration guide. |
| Docs + changelog | A warning on the reference page and a dated changelog entry under Deprecated. |
HTTP/1.1 200 OK
Deprecation: true
Sunset: Wed, 07 Apr 2027 00:00:00 GMT
Link: <https://fomodata.dev/docs/changelog>; rel="deprecation"Watch for the header
Log a warning whenever a response carries Deprecation. It's the earliest signal you'll get, before any change in behaviour.
When v2 arrives
/v2 will run side by side with /v1, with a migration guide and a sunset date for v1 at least as generous as any deprecation above. Keys, projects, webhooks and events carry over; only the request and response shapes change.