Compatibilité
Compatibilité
Ce que nous pouvons changer dans v1 sans préavis, et ce qui exigerait une nouvelle version majeure. Énoncé sous forme de liste plutôt que de promesse, afin qu'une intégration puisse se prémunir contre exactement le bon ensemble.
Les chemins, les méthodes, les portées, les noms de champs et les codes d'erreur sont publiés en anglais, car l'anglais est la langue de l'interface elle-même : c'est ce qu'un appelant saisit ou compare. Il en va de même de chaque exemple de code, de chaque charge utile JSON et de la phrase exacte que porte une réponse d'erreur : /v1 ne lit pas Accept-Language, et traduire ce que l'API envoie réellement en donnerait une description fausse. Tout ce qui est écrit à leur sujet suit la langue de cette page.
La révision actuelle est 2026-08-01. Le chemin reste /v1 ; la révision désigne le document qui le décrit.
Changements que nous n'apporterons pas à v1
Ceux-ci exigent une nouvelle version majeure. Si nous devions un jour en publier une, les versions existantes continueraient de répondre pendant la migration.
- Supprimer une opération.
- Supprimer ou renommer un paramètre, ou un champ d'une réponse.
- Ajouter un nouveau paramètre obligatoire.
- Rendre obligatoire un paramètre jusque-là facultatif.
- Changer le type d'un paramètre ou d'un champ de réponse.
- Retirer une valeur d'une énumération.Un client qui s'aiguille sur cette valeur n'a aucune branche pour son absence : il échoue alors de la manière dont son langage échoue sur un cas non traité.
- Ajouter une nouvelle règle de validation à un paramètre existant.Une requête qui passait hier se mettrait à échouer : c'est un retrait de capacité déguisé en correction de bogue.
- Modifier les exigences d'authentification ou d'autorisation, y compris la portée qu'exige une opération.
Changements que nous pouvons apporter à tout moment
Votre intégration doit tous les tolérer. Ils se produiront, et ils ne seront pas annoncés.
- Ajouter une nouvelle opération.
- Ajouter un nouveau paramètre facultatif.
- Ajouter un nouvel en-tête de requête facultatif.
- Ajouter un nouveau champ à une réponse.Analysez les réponses avec indulgence : un client qui rejette les champs inconnus cassera dès notre premier ajout.
- Ajouter un nouvel en-tête de réponse.
- Ajouter une valeur à une énumération.Traitez une valeur non reconnue comme un cas par défaut plutôt que comme une erreur. De nouvelles catégories de passeports et de nouveaux types d'événements apparaîtront.
- Scinder un code d'erreur en codes plus précis — mais seulement là où le code d'origine ne pouvait pas être levé par une logique d'exécution, une reprise par exemple.Scinder un code sur lequel un client S'AIGUILLE est un changement cassant ; scinder un code qu'il se contente de journaliser ne l'est pas. Toute la différence tient à ce qu'un comportement en dépendait ou non.
Ce que votre client doit tolérer
Chacun de ces points correspond à un changement ci-dessus que nous nous réservons le droit de faire. Un client qui en enfreint un cassera sur quelque chose que nous considérons comme une routine.
- Ignorez les champs de réponse que vous ne reconnaissez pas, plutôt que de rejeter la réponse entière.
- Traitez une valeur d'énumération non reconnue comme un cas par défaut, non comme une erreur.
- Traitez les identifiants comme des chaînes opaques : ne les analysez jamais, n'y cherchez jamais de motif.
- Ne dépendez ni de l'ORDRE des champs dans un objet JSON, ni de la formulation exacte d'un message d'erreur destiné à un humain. Aiguillez-vous plutôt sur le code d'erreur, lisible par machine.
- En cas de 429, et pour tout autre refus porteur d'un en-tête Retry-After, réessayez après le délai qu'il indique. Cet en-tête n'appartient pas qu'au 429 : un 409 resource_busy, un 503 storage_unavailable et un 503 entitlement_unavailable le portent aussi, car réessayer y est le remède.
- Reprenez un 5xx avec une NOUVELLE Idempotency-Key. Une clé qui a enregistré une erreur serveur rejoue cette erreur pendant toute la durée de rétention — délibérément : l'échec peut avoir été une réponse perdue à une écriture qui, elle, avait ABOUTI, et c'est précisément ce rejeu sur la même clé qui empêche une écriture ratée d'en devenir deux.
- Surveillez les en-têtes de réponse Deprecation et Sunset, ainsi que le Link: rel="successor-version" qui les accompagne. C'est ainsi qu'est annoncée la suppression d'un point de terminaison, et l'annonce arrive bien avant que celui-ci cesse de répondre.
Traitez chaque identifiant comme une chaîne opaque d'au plus 255 caractères. Ne les analysez pas, ne validez pas leur format, et ne présumez pas qu'il s'agit d'UUID — le format peut changer sans préavis.
Obsolescence
Un point de terminaison voué à disparaître répond avec les en-têtes Deprecation et Sunset, ainsi qu'un en-tête Link nommant son successeur. Ils arrivent bien avant que le point de terminaison cesse de répondre. Surveillez-les.