Versions et dépréciation
Attention : l’API n’est pas encore en service
Ses versions commencent par 0 : selon SemVer, tout peut encore changer avant la version 1.0.0.
Numéros de version
Section intitulée « Numéros de version »Le contrat de l’API est versionné par son chemin : chaque route commence par /v1.
Les versions publiées suivent SemVer 2.0.0, à partir des changements fusionnés :
- un correctif augmente le dernier nombre (
1.4.2devient1.4.3) ; - une nouveauté augmente celui du milieu (
1.4.3devient1.5.0) ; - un changement cassant augmente le premier (
1.5.0devient2.0.0).
Avant la version 1.0.0, un changement cassant n’augmente que le nombre du milieu.
Dépréciation
Section intitulée « Dépréciation »Quand une version ou un champ du contrat public va être retiré, les réponses de l’API te le disent avec deux en-têtes :
Deprecation(RFC 9745) : la date à partir de laquelle ce que tu appelles est déprécié ;Sunset(RFC 8594) : la date à partir de laquelle il ne répondra plus.
Entre ces deux dates, il y a au moins six mois. Voici leur forme, avec des dates d’exemple :
Deprecation: @1798761600Sunset: Thu, 01 Jul 2027 00:00:00 GMTDeprecation donne un horodatage Unix précédé de @ (ici le 1er janvier 2027), Sunset une date HTTP. Repère ces en-têtes dans tes journaux pour migrer avant la date de retrait.
Source : les standards de l’API.
Journal des versions
Section intitulée « Journal des versions »Chaque version liste les changements fusionnés dans l’API. Leurs titres restent en anglais, comme dans son dépôt. Le même journal est publié dans les versions GitHub de l’API.