# Versionnage et dépréciation de l'API

> Comment l'API REST d'Endless est versionnée avec l'en-tête Endless-Api-Version, ce qui peut changer au sein d'une version et le préavis de dépréciation de 180 jours.

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

L'API REST d'Endless sur `https://api.endless.app` est versionnée par un en-tête de requête, pas par l'URL. Rien n'est déprécié aujourd'hui.

## Fixer une version

La version actuelle est la **1.0.0**. Les chemins ne contiennent pas de version (`/assets`, pas `/v1/assets`).

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

- Seule la version majeure compte : `1` et `1.0.0` signifient la même chose.
- Si vous omettez l'en-tête, la version actuelle est acceptée.
- Chaque réponse porte `Endless-Api-Version` avec la version qui l'a servie.
- Une version majeure que l'API ne peut pas servir échoue avec `400` et `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"
  }
}
```

## Ce qui change au sein d'une version majeure

Uniquement des ajouts : nouvelles opérations, nouvelles entrées facultatives, nouveaux champs dans les réponses. Ignorez les champs de réponse que vous ne reconnaissez pas. Supprimer une opération ou un champ, ou changer le type d'un champ, constitue une nouvelle version majeure.

## Dépréciation

Une opération dépréciée continue de fonctionner **au moins 180 jours** après la publication de son premier en-tête `Deprecation`, et sa date `Sunset` n'est jamais antérieure. Chacune de ses réponses porte ces signaux :

| Signal                                                                     | Ce qu'il vous indique                                                   |
| -------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| En-tête `Deprecation` ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)) | L'opération est dépréciée, et depuis quand                              |
| En-tête `Sunset` ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594))      | Quand l'opération cesse de fonctionner                                  |
| En-tête `Link` avec `rel="deprecation"`                                    | Où se trouve la note de migration                                       |
| `deprecated: true` dans le document OpenAPI                                | La même information, pour un client généré à partir de la spécification |

## Sources lisibles par une machine

- [Document OpenAPI](https://api.endless.app/openapi.json) : `info.description` décrit cette politique et `info.version` est la version actuelle.
- [Index de l'API](https://api.endless.app/) : son objet `versioning` liste l'en-tête, la version actuelle, les versions majeures prises en charge et `deprecation_notice_days`.
- [Référence de l'API](/docs/api) : chaque opération, générée à partir du document OpenAPI.