Versionnage et dépréciation de l'API

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 versionCopier le lien

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

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 :

{
  "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 majeureCopier le lien

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éciationCopier le lien

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 :

Sources lisibles par une machineCopier le lien

• Document OpenAPI : info.description décrit cette politique et info.version est la version actuelle.
• Index de l'API : 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 : chaque opération, générée à partir du document OpenAPI.