# Ticket Fairy public API: versioning and deprecation policy

This policy applies to the public consumer API at `https://www.ticketfairy.com/api/v1/`. The OpenAPI description is at https://www.ticketfairy.com/api/v1/openapi.json.

## Current status

No operation, parameter or response field in `v1` is deprecated. No response sends a `Deprecation` or `Sunset` header.

## Versions

The major version is in the path, for example `/api/v1/events/listing`.

Inside a version, we make only additive changes:

- New endpoints.
- New optional query parameters.
- New fields in a response object.
- New values in a field that the OpenAPI description does not limit to a fixed list.

Your client must ignore response fields that it does not know.

A change that can break a working client goes into a new version path, for example `/api/v2/`. Such changes include these:

- Removing or renaming an endpoint, a parameter or a response field.
- Changing the type or the meaning of a field.
- Making an optional parameter required, or accepting fewer values than before.

## How we announce a deprecation

When we plan to retire an operation or a parameter, we do these steps:

1. We mark it `deprecated: true` in the OpenAPI description.
2. Every response from the deprecated operation, or to a request that uses the deprecated parameter, sends these headers:
   - `Deprecation: @<Unix time>` (RFC 9745). This is the date from which the item is deprecated.
   - `Sunset: <HTTP-date>` (RFC 8594). This is the date from which the item can stop working.
   - `Link: <https://www.ticketfairy.com/api/v1/versioning.md>; rel="deprecation"`. When a replacement exists, a second link has `rel="successor-version"` and points to it.
3. We keep the item working until the Sunset date.

The Sunset date is at least 6 months after the Deprecation date. We shorten this period only when a security or legal requirement makes it necessary. In that case, we still send both headers.

## Pagination

List endpoints return a `pagination` object. Follow `pagination.nextCursor`: send its value as the `cursor` query parameter, together with the same filters, to get the next page. When `nextCursor` is `null`, there are no more pages. The `page` and `size` parameters continue to work in `v1`.