# API versioning and deprecation

> How the Endless REST API is versioned with the Endless-Api-Version header, what can change in a version, and the 180-day deprecation notice.

Source: https://endless.okinawa/docs/reference/api-versioning

The Endless REST API at `https://api.endless.app` is versioned by a request header, not the URL. Nothing is deprecated today.

## Pin a version

The current version is **1.0.0**. Paths have no version segment (`/assets`, not `/v1/assets`).

```http
Endless-Api-Version: 1
```

* Only the major counts: `1` and `1.0.0` mean the same thing.
* Omitting the header accepts the current version.
* Every response carries `Endless-Api-Version` with the version that served it.
* A major the API can't serve fails with `400` and `unsupported_api_version`:

```json
{
  "code": "BAD_REQUEST",
  "status": 400,
  "message": "This deployment serves API version 1.0.0; the request asked for 2.",
  "data": {
    "code": "unsupported_api_version",
    "hint": "Send `Endless-Api-Version: 1`, or omit the header to accept the current version.",
    "documentation": "https://endless.app/docs/api"
  }
}
```

## What changes inside a major

Only additions: new operations, new optional inputs, new response fields. Ignore response fields you don't recognize. Removing an operation or field, or changing a field's type, is a new major.

## Deprecation

A deprecated operation keeps working for **at least 180 days** after its first `Deprecation` header ships, and its `Sunset` date is never sooner. Every response from it carries these signals:

| Signal                                                                    | What it tells you                              |
| ------------------------------------------------------------------------- | ---------------------------------------------- |
| `Deprecation` header ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)) | The operation is deprecated, and since when    |
| `Sunset` header ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594))      | When the operation stops working               |
| `Link` header with `rel="deprecation"`                                    | Where the migration note is                    |
| `deprecated: true` in the OpenAPI document                                | The same, for a client generated from the spec |

## Machine-readable sources

* [OpenAPI document](https://api.endless.app/openapi.json): `info.description` states this policy, `info.version` is the current version.
* [API index](https://api.endless.app/): its `versioning` object lists the header, current version, supported majors and `deprecation_notice_days`.
* [API reference](/docs/api): every operation, generated from the OpenAPI document.