# 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.

Source: https://docs.fiest.io/api/versioning

Every operation lives under `/v1`. The `info.version` field of the OpenAPI
document ([JSON](https://docs.fiest.io/openapi.json),
[YAML](https://docs.fiest.io/openapi.yaml)) names the current release.

## The contract can still break [#subject-to-change]

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 [#compatible-changes]

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](/api/reference/errors).

## Changes that count as breaking [#breaking-changes]

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 [#deprecation]

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 [#current-announcements]

None. Nothing in the Partner API is scheduled for removal.

## Rate limits [#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 [#where-to-look]

* The OpenAPI document lists these headers on every operation and repeats
  this policy in its description.
* [API error codes](/api/reference/errors) has every stable error code and
  whether to retry it.
* Questions about an announced change go to
  [support@fiest.io](mailto:support@fiest.io).