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

L'API d'intégration Enkore évolue dans le temps : de nouveaux champs apparaissent, certains sont renommés, des comportements sont affinés. Pour que ces évolutions n'interrompent jamais une intégration déjà en production, l'API est versionnée par révision datée.

Ce document explique comment indiquer la révision que vous souhaitez utiliser, ce qui se passe par défaut, et selon quelle politique une révision est dépréciée puis retirée.

Principe

Une révision identifie une version du contrat de l'API : structure des requêtes, structure des réponses, comportement.
Vous choisissez la révision en envoyant le header HTTP revision dans vos requêtes.
Une révision est nommée par une date au format YYYY-MM-DD (ex : 2026-06-18), correspondant au jour de sa mise à disposition.
Une fois publiée, une révision ne change plus de manière incompatible. Votre intégration reste donc stable tant que vous ne changez pas la révision demandée.

Indiquer une révision

Ajoutez le header revision à votre requête :

POST /api/order/register HTTP/1.1
Host: api.enkore.io
Authorization: Basic <votre_clé_api>
Content-Type: application/json
revision: 2026-06-18

Exemple en curl :

curl -X POST https://api.enkore.io/api/order/register \
  -u "<votre_clé_api>:" \
  -H "Content-Type: application/json" \
  -H "revision: 2026-06-18" \
  -d '{ ... }'

Comportement par défaut (sans header)

Si vous n'envoyez aucun header revision, l'API sert le contrat historique — c'est-à-dire la révision la plus ancienne encore supportée.

Cela garantit qu'une intégration développée avant l'introduction du versionnage continue de fonctionner à l'identique, sans aucune modification. Vous n'êtes donc jamais obligé d'envoyer le header pour rester opérationnel.

astuce

Pour toute nouvelle intégration, nous recommandons de fixer explicitement la révision la plus récente disponible et de l'envoyer systématiquement. Vous bénéficiez ainsi du contrat le plus à jour, et vous maîtrisez le moment de vos futures migrations.

Révisions disponibles

Révision	Statut	Description
`2026-08-26`	Stable	Les erreurs sont servies au format RFC 9457 (`application/problem+json`), avec un champ `type` stable par motif de refus. Le contrat des endpoints est inchangé par rapport à `2026-06-18`.
`2026-06-18`	Stable	Champ `externalRef` renommé en `externalId` sur les commandes, ajout du champ optionnel `externalReference`.
`2026-01-01`	Stable	Contrat historique (servi par défaut en l'absence de header `revision`).

Cette liste est tenue à jour à chaque nouvelle révision. La révision la plus récente est toujours celle à privilégier pour une nouvelle intégration.

Gestion des erreurs

Le header revision est validé strictement :

Cas	Réponse
Pas de header `revision`	`200` — le contrat historique est servi
Révision connue et valide	`200` — la révision demandée est servie
Format invalide (≠ `YYYY-MM-DD`)	`400 Bad Request`
Révision inconnue	`400 Bad Request`

Il n'y a pas de repli silencieux : une révision mal formée ou inexistante provoque une erreur explicite, afin d'éviter qu'une faute de frappe ne vous serve un contrat inattendu.

:::info Format du corps d'erreur Les exemples ci-dessous sont au format historique, servi aux révisions antérieures à 2026-08-26. À partir de cette révision, les erreurs suivent la RFC 9457 et identifient leur motif par une URI stable — voir Format des erreurs de l'API. Les deux refus ci-dessous y portent les motifs invalid-revision-header et unknown-api-revision. :::

Exemple de réponse 400 — format invalide :

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid 'revision' header '2026/06/18'. Expected a date in 'YYYY-MM-DD' format."
}

Exemple de réponse 400 — révision inconnue :

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Unknown API revision '2025-01-01'. Supported revisions: 2026-01-01, 2026-06-18, 2026-08-26."
}

Cycle de vie d'une révision

Chaque révision suit un cycle de vie en trois phases, sur deux ans au total :

Phase	Durée	Ce que cela signifie
Stable	1 an	La révision est pleinement supportée et recommandée.
Dépréciée	1 an	La révision fonctionne encore mais ne doit plus être utilisée pour de nouvelles intégrations. C'est la fenêtre pour migrer.
Retirée	—	La révision n'est plus supportée.

Pendant la phase de dépréciation, vous disposez donc d'une année complète pour migrer vers une révision plus récente avant le retrait.

Headers de dépréciation

Lorsqu'une révision est dépréciée, l'API ajoute automatiquement à ses réponses les headers standards RFC 8594 :

Header	Description
`Deprecation`	Date à laquelle la révision est passée en dépréciation.
`Sunset`	Date de retrait prévue, après laquelle la révision ne sera plus servie.

Exemple :

HTTP/1.1 200 OK
Deprecation: Fri, 18 Jun 2027 00:00:00 GMT
Sunset: Sun, 18 Jun 2028 00:00:00 GMT

astuce

Nous recommandons de journaliser et surveiller la présence des headers Deprecation et Sunset dans vos réponses : ils constituent votre signal automatique pour planifier une migration avant le retrait de la révision.

Changements compatibles vs. incompatibles

Toutes les évolutions ne nécessitent pas une nouvelle révision.

Changements compatibles (pas de nouvelle révision)

Ces changements peuvent être déployés au sein d'une révision existante, car ils ne cassent pas une intégration correctement implémentée :

Ajout d'un nouveau champ optionnel dans une requête.
Ajout d'un nouveau champ dans une réponse.
Ajout d'un nouvel endpoint.
Ajout d'une nouvelle valeur à une énumération existante.

Bonne pratique : votre intégration doit ignorer les champs inconnus qu'elle reçoit, plutôt que de les rejeter.

Changements incompatibles (nouvelle révision)

Ces changements sont introduits via une nouvelle révision datée, sans modifier les révisions existantes :

Suppression ou renommage d'un champ.
Modification du type ou du format d'un champ.
Suppression d'un endpoint.
Changement de comportement existant.

Stratégie de montée de version

Migrer vers une révision plus récente se fait en quelques étapes :

Consultez le tableau des révisions ci-dessus pour identifier la révision cible et le détail des changements.
Adaptez votre intégration au nouveau contrat (champs renommés, nouveaux champs, etc.).
Mettez à jour le header revision envoyé dans vos requêtes vers la nouvelle date.
Testez sur un environnement de recette avant le déploiement en production.
Une migration étant un simple changement de la valeur du header, vous pouvez revenir en arrière instantanément en cas de problème, tant que l'ancienne révision n'est pas retirée.

Exemple : migrer de `2026-01-01` vers `2026-06-18`

La révision 2026-06-18 renomme le champ externalRef en externalId sur les commandes et ajoute le champ optionnel externalReference.

Avant (revision: 2026-01-01) :

{
  "externalRef": 42
}

Après (revision: 2026-06-18) :

{
  "externalId": 42,
  "externalReference": "CMD-2026-0042"
}

La migration consiste donc à renommer externalRef en externalId, à ajouter optionnellement externalReference, puis à passer le header revision à 2026-06-18.

Bonnes pratiques

Fixez explicitement une révision pour toute nouvelle intégration, et envoyez-la dans chaque requête.
Surveillez les headers Deprecation / Sunset pour anticiper les migrations.
Ignorez les champs inconnus dans les réponses pour absorber les changements non incompatibles sans modification.
Migrez pendant la fenêtre de dépréciation (un an), sans attendre le retrait.

Principe​

Indiquer une révision​

Comportement par défaut (sans header)​

Révisions disponibles​

Gestion des erreurs​

Cycle de vie d'une révision​

Headers de dépréciation​

Changements compatibles vs. incompatibles​

Changements compatibles (pas de nouvelle révision)​

Changements incompatibles (nouvelle révision)​

Stratégie de montée de version​

Exemple : migrer de 2026-01-01 vers 2026-06-18​

Bonnes pratiques​