Versioning and deprecation
The Partner API is versioned in the URL path and is still below 1.0. This page says what can change, how Fiest tells you, and which headers mark a retiring version or operation.
Every operation lives under /v1. The info.version field of the OpenAPI
document (JSON,
YAML) names the current release.
The contract can still break
The version is below 1.0, and we may change the contract in ways that break a client. We register every partner client ourselves, so before a breaking change ships we tell the affected partners directly and list the change on this page. We do not promise a notice period, and we do not keep old behaviour around for a fixed time.
Changes you will not hear about
These can appear at any time. Build your client so they do not break it:
- New operations.
- New optional request fields and query parameters.
- New fields in responses. Ignore any field you do not know.
- New error codes. Branch on the documented codes and fall back to the HTTP status for any code you do not know. See API error codes.
Changes that count as breaking
Removing or renaming an operation, field or scope. Changing what a field means or what type it has. Rejecting a request that used to pass validation. Changing what you need to authenticate.
How a retiring version or operation tells you
When we schedule a version or an operation for removal, we list it below. Until it stops answering, every response from it carries three headers, so your client can notice at runtime without anyone reading this page again.
| Header | Standard | Value |
|---|---|---|
Deprecation | RFC 9745 | When we announced it, as @<seconds since 1970-01-01 UTC>. |
Sunset | RFC 8594 | The HTTP date after which it stops answering. |
Link | RFC 8288 | <notice URL>; rel="deprecation", pointing at the entry below. |
Log Deprecation whenever you see it. If Sunset is present, move off the
old version before that date.
Current announcements
None. Nothing in the Partner API is scheduled for removal.
Rate limits
Each partner client gets 60 requests per 60 seconds for each authorizing
user. Past that, the API answers 429 rate_limited with a Retry-After
header. Wait that many seconds, then retry. If the request was a write,
resend it with the same idempotency key.
The same policy appears in two IETF RateLimit header fields:
RateLimit-Policy ("partner";q=60;w=60) on every response, and
RateLimit ("partner";r=0;t=<seconds>) on a 429. The served
/openapi.json documents them once the release that sends them is live.
If a response lacks them, the limit still applies.
Where to look
- The OpenAPI document lists these headers on every operation and repeats this policy in its description.
- API error codes has every stable error code and whether to retry it.
- Questions about an announced change go to support@fiest.io.