Changements de l'API

Abuna garde l'API fonctionnelle pour le code que vous écrivez aujourd'hui. Certains changements arrivent à tout moment, parce que le code écrit comme cette page le décrit continue de fonctionner malgré eux. Tous les autres changements sont annoncés 90 jours à l'avance.

Changements sans préavis

Ils peuvent survenir à tout moment. Écrivez votre code pour qu'il continue de fonctionner lorsqu'ils arrivent :

• Un nouveau champ dans une réponse, un objet, ou le data d'un événement. Ignorez les champs que vous ne connaissez pas.
• Un nouveau type d'événement. Répondez 2xx à un webhook dont vous ne gérez pas le type, et ignorez-le.
• Un nouvel endpoint, ou un nouveau paramètre facultatif sur un endpoint existant.
• Une nouvelle valeur dans un champ qui liste ses valeurs, comme un nouveau kind de notification ou un nouveau code d'erreur. Traitez une valeur inconnue comme la plus proche que vous connaissez, ou journalisez-la.
• Une nouvelle paire dans l'en-tête X-Abuna-Signature. Lisez les paires que vous connaissez et ignorez le reste.
• Des identifiants et des curseurs d'une longueur ou d'une forme nouvelle. Traitez-les comme des chaînes opaques. Voir les identifiants.
• Une nouvelle formulation dans la phrase error d'une erreur. Branchez sur code, jamais sur la phrase.

Changements annoncés 90 jours à l'avance

Tout autre changement qui pourrait casser du code fonctionnel est annoncé au moins 90 jours avant de prendre effet. Cela comprend la suppression ou le renommage d'un endpoint, d'un champ ou d'un type d'événement, le changement du type ou du sens d'un champ, le passage d'un paramètre facultatif à obligatoire, et la modification de la signature des webhooks.

Pendant ces 90 jours, l'ancien comportement reste en place. L'entrée du journal des modifications indique ce qui change, la date d'entrée en vigueur, et ce qu'il faut modifier dans votre code.

Comment vous êtes informé des changements

Chaque changement figure dans le journal des modifications avec sa date. Un changement annoncé y est inscrit le jour où les 90 jours commencent.