# API-Versionierung und Deprecation

> Wie die Endless-REST-API mit dem Header Endless-Api-Version versioniert wird, was sich innerhalb einer Version ändern kann und die Deprecation-Frist von 180 Tagen.

Source: https://endless.app/de/docs/reference/api-versioning

Die Endless-REST-API unter `https://api.endless.app` wird über einen Request-Header versioniert, nicht über die URL. Aktuell ist nichts deprecated.

## Version festlegen

Die aktuelle Version ist **1.0.0**. Pfade haben kein Versionssegment (`/assets`, nicht `/v1/assets`).

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

- Nur die Hauptversion zählt: `1` und `1.0.0` bedeuten dasselbe.
- Ohne den Header akzeptierst du die aktuelle Version.
- Jede Antwort trägt `Endless-Api-Version` mit der Version, die sie geliefert hat.
- Eine Hauptversion, die die API nicht bedienen kann, scheitert mit `400` und `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"
  }
}
```

## Was sich innerhalb einer Hauptversion ändert

Nur Ergänzungen: neue Operationen, neue optionale Eingaben, neue Felder in Antworten. Ignoriere Antwortfelder, die du nicht kennst. Eine Operation oder ein Feld zu entfernen oder den Typ eines Felds zu ändern, ist eine neue Hauptversion.

## Deprecation

Eine veraltete Operation funktioniert **mindestens 180 Tage** weiter, nachdem ihr erster `Deprecation`-Header ausgeliefert wurde, und ihr `Sunset`-Datum liegt nie früher. Jede Antwort von ihr trägt diese Signale:

| Signal                                                                    | Was es dir sagt                                              |
| ------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `Deprecation`-Header ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)) | Die Operation ist veraltet, und seit wann                    |
| `Sunset`-Header ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594))      | Wann die Operation nicht mehr funktioniert                   |
| `Link`-Header mit `rel="deprecation"`                                     | Wo der Migrationshinweis steht                               |
| `deprecated: true` im OpenAPI-Dokument                                    | Dasselbe, für einen aus der Spezifikation generierten Client |

## Maschinenlesbare Quellen

- [OpenAPI-Dokument](https://api.endless.app/openapi.json): `info.description` beschreibt diese Policy, `info.version` ist die aktuelle Version.
- [API-Index](https://api.endless.app/): Sein Objekt `versioning` listet den Header, die aktuelle Version, die unterstützten Hauptversionen und `deprecation_notice_days`.
- [API-Referenz](/docs/api): jede Operation, generiert aus dem OpenAPI-Dokument.