Versions

Chaque chemin commence par /v1. Au sein de v1, l’API n’évolue que de façon à ne pas casser les clients existants. Un changement incompatible serait une /v2, servie à côté de /v1.

Évolutions compatibles

Elles peuvent survenir à tout moment au sein de v1 :

• une nouvelle ressource ou opération ;
• un nouveau paramètre facultatif ;
• un nouveau champ dans un objet ;
• une nouvelle valeur dans une énumération ;
• un nouveau code d’erreur ;
• un autre ordre des champs ;
• une autre longueur ou un autre format des identifiants et des jetons.

Ce qui ne change jamais au sein de la v1

• Un champ, un paramètre, un chemin, une valeur d’énumération ou un code d’erreur n’est jamais renommé, retypé ni supprimé.
• Un paramètre facultatif ne devient jamais obligatoire.
• Une valeur par défaut ne change jamais, comme le limit par défaut ou l’ordre des listes.

Écrire un client qui continue de fonctionner

• Ignorez les champs que vous ne connaissez pas. N’échouez pas quand un objet a un champ de plus.
• Acceptez les valeurs d’énumération inconnues. Un status peut gagner une valeur : traitez-la de façon neutre plutôt que comme une erreur.
• Acceptez les codes d’erreur inconnus. Fiez-vous au statut HTTP et au type de l’erreur.
• Ne dépendez pas de la forme des identifiants. Stockez-les comme des chaînes opaques, sans supposer de longueur ni de motif.

Des formes stables

Un champ est toujours présent : null s’il n’a pas de valeur, [] pour une liste vide. Les exceptions sont total_count et les champs que les listes laissent de côté par défaut, présents seulement si vous les demandez. Les valeurs d’énumération sont en minuscules, et les dates sont des horodatages Unix en secondes, en UTC.

Rester informé

Chaque changement figure dans le journal des modifications, avec sa date.