Versionnement

L’API utilise un chemin stable /v1 associé à un versionnement basé sur la date transporté dans un en-tête de requête. Cela nous permet de faire évoluer les structures de réponse au fil du temps sans casser les intégrations existantes.

L’en-tête Service-Version

Les versions sont des chaînes de date, par exemple 2026-06-27. Envoyez-en une avec n’importe quelle requête :

curl https://api.useservice.app/v1/reservations \
  -H "Authorization: Bearer $SERVICE_API_KEY" \
  -H "Service-Version: 2026-06-27"

Comment la version est résolue

1. Épinglée à chaque clé. Chaque clé d’API est épinglée à une version lors de sa création. Si vous n’envoyez aucun en-tête Service-Version, cette version épinglée est utilisée. Votre intégration continue ainsi de fonctionner sans changement, même lorsque de nouvelles versions sont publiées.
2. Remplacement par requête. Si vous envoyez un en-tête Service-Version, il remplace la version épinglée de la clé pour cette seule requête — utile pour tester une version plus récente avant de l’adopter.

Renvoyée dans les réponses

Chaque réponse renvoie la version qui l’a servie, afin que vous puissiez confirmer exactement quel comportement vous avez obtenu :

HTTP/1.1 200 OK
Service-Version: 2026-06-27
Content-Type: application/json

Version actuelle

Il existe actuellement une seule version : 2026-06-27. Lorsque de nouvelles versions seront introduites, cette page les listera ainsi que les changements apportés par chacune. Les points de terminaison de webhook sont eux aussi épinglés à une version à leur création, afin que les charges utiles que vous recevez restent cohérentes. Voir Webhooks.