Ce qui peut changer, ce qui ne changera pas sans préavis, et combien de temps vous avez pour réagir.
La version majeure figure dans le chemin : aujourd'hui, /api/v2. Le jour où une évolution ne pourra plus être rétrocompatible, elle deviendra /api/v3. C'est la seule chose qui puisse casser une intégration, et elle est visible dans chaque URL que vous appelez.
Une majeure publiée n'est jamais modifiée de façon cassante : un champ n'est ni supprimé, ni renommé, ni changé de type ; un identifiant reste stable ; une valeur d'énumération n'est pas réaffectée. Ces changements attendent la majeure suivante.
À l'intérieur d'une majeure, nous ajoutons librement : de nouveaux champs dans une réponse existante, de nouveaux endpoints, de nouveaux paramètres de requête facultatifs. Aucun de ces ajouts n'est annoncé, parce qu'aucun ne casse un client correctement écrit.
La contrepartie est à votre charge : votre client doit tolérer les champs inconnus. Un parseur strict, qui rejette la réponse entière sur une clé qu'il ne connaît pas, cassera sur un ajout que cette politique autorise explicitement.
Quand un endpoint est voué au retrait, il commence à répondre avec la date de ce retrait et l'en-tête Deprecation. Entre cette première réponse et la date annoncée, il s'écoule au minimum six mois. Pendant tout ce délai l'endpoint continue de fonctionner normalement.
Ce délai est la raison d'être des en-têtes : une intégration qui les journalise apprend le retrait le jour où il est décidé, sans avoir à surveiller cette page.
Les trois derniers suivent la RFC 8594. Ils n'apparaissent que sur un endpoint effectivement voué au retrait.
| En-tête | Exemple | Ce qu'il dit |
|---|---|---|
| X-API-Version | 2 | La version majeure qui a répondu. Toujours présente, y compris sur une erreur. |
| X-API-Stable | true | La version est publiée et tenue. Une version instable serait annoncée comme telle avant d'être ouverte. |
| Deprecation | true | L'endpoint appelé est voué au retrait. Absent tant qu'il ne l'est pas. |
| Sunset | Mon, 01 Mar 2027 00:00:00 GMT | La date à laquelle l'endpoint cessera de répondre. Toujours au moins six mois après l'apparition de Deprecation. |
| Link | <…/docs/api/versioning>; rel="sunset" | Où lire ce qu'il faut appeler à la place. Accompagne systématiquement Sunset. |
X-API-Version: 2 X-API-Stable: true Deprecation: true Sunset: Mon, 01 Mar 2027 00:00:00 GMT Link: <https://ethniafrica.com/docs/api/versioning>; rel="sunset"
Les deux premiers en-têtes sont présents sur toutes les réponses de /api/v2, y compris les erreurs — une 401 sans clé valide et une 429 de limitation de débit les portent aussi.