Skip to main content
La version est dans l’URL : /api/v1. Une future v2 sera publiée à côté de la v1, jamais à sa place.

​
Notre engagement

Sans préavis, dans la v1

  • Ajouter un endpoint
  • Ajouter un champ optionnel en entrée
  • Ajouter un champ en sortie
  • Ajouter une permission
  • Ajouter un type d’événement webhook

Cela imposera une v2

  • Supprimer ou renommer un champ ou un endpoint
  • Rendre obligatoire un champ jusque-là optionnel
  • Changer le type ou le sens d’un champ existant
  • Changer la signification d’un événement existant

​
Écrivez un client tolérant

Trois règles qui éviteront que votre intégration casse sur une évolution pourtant compatible :
1

Ignorez les champs inconnus

Ne validez pas nos réponses en mode strict. Nous ajoutons régulièrement des champs.
2

Ne dépendez pas de l'ordre des clés JSON

Il n’est pas garanti et peut changer d’une version à l’autre de notre runtime.
3

Ne plantez pas sur une valeur d'énumération inconnue

C’est le piège qui casse le plus d’intégrations en pratique. Si action vaut demain une valeur que vous ne connaissez pas, journalisez-la et poursuivez — ne levez pas d’exception.

​
Dépréciation

Le jour où une v2 existera, les endpoints v1 renverront les en-têtes Deprecation et Sunset (RFC 8594), avec un préavis minimum de six mois avant toute extinction. Les changements sont annoncés dans cette documentation.

​
Webhooks

Le champ type d’un événement est le contrat.
  • Enrichir data avec de nouveaux champs est non cassant : traitez-les comme optionnels.
  • Changer la sémantique d’un événement donne lieu à un nouveau type, jamais à une mutation silencieuse de l’existant.
Filtrez donc toujours sur type avant de traiter une livraison, et ignorez les types que vous ne connaissez pas — vous en recevrez de nouveaux au fil du temps si vous y êtes abonné.