Gestion des versions

L’API v1 est gelée depuis le lancement. Le code écrit pour elle continue de fonctionner : elle gagne des endpoints et des champs, et ne perd rien.

Ce qui peut changer dans la v1

• De nouveaux endpoints, ainsi que de nouveaux champs de requête et options facultatifs, désactivés par défaut.
• De nouveaux champs dans les réponses et dans les événements de webhook. Ignorez les champs que vous ne connaissez pas.
• De nouveaux codes d’erreur, uniquement pour de nouvelles fonctionnalités ; une requête existante ne reçoit jamais un nouveau code pour une ancienne raison.
• De nouveaux types d’événements de webhook, envoyés uniquement aux endpoints qui les demandent.
• Les messages d’erreur, destinés aux humains : basez votre logique sur le code, jamais sur le message.
• Des limites plus élevées, davantage de formats, des réponses plus rapides.

Ce qui ne change jamais dans la v1

• Le chemin d’un endpoint, sa méthode, ou le sens de ses champs et de ses réponses.
• Le nom ou le type d’un champ, une valeur par défaut, ou le statut et le sens d’un code d’erreur.
• Ce qui compte comme un marquage, tel que l’indique la page des tarifs, sans préavis aux clients existants.
• Le schéma de signature des webhooks (Kennmarq-Signature) et les formats du journal de transparence.

Une modification incompatible

Elle arriverait sous la forme d’une v2, avec ses propres chemins, annoncée au moins 12 mois à l’avance dans le journal des modifications et par e-mail aux propriétaires de chaque organisation. La v1 continue de répondre pendant au moins ces 12 mois. La correction d’un problème de sécurité est la seule exception : si une requête n’est pas sûre en l’état, nous la modifions immédiatement et l’indiquons dans le journal des modifications.

OpenAPI

La v1 est décrite dans un document OpenAPI 3.1 à l’adresse https://api.kennmarq.com/v1/openapi.json, pour les générateurs de clients et les outils d’API. Il recense tous les endpoints, champs et codes d’erreur que décrit cette référence.