Gestion des versions d’API
La version de l’API influencera les structures des objets de requête et de réponse ainsi que la fonctionnalité disponible par le biais de l’API. Une nouvelle version de l’API ne sera introduite que si nous apportons une modification non rétrocompatible susceptible d’avoir un impact sur vos intégrations existantes. Vous pouvez gérer le moment de la mise à niveau vers la dernière version, ce qui vous permet de vous assurer que votre intégration n’est pas perturbée par la mise à disposition de nouvelles fonctionnalités.
Version majeure de l’API
La version majeure (c’est-à-dire /v1/ ) représente un changement technologique majeur entre les versions de l’API. Les modifications de la version majeure sont réservées aux modifications à grande échelle de l’API qui modifient fondamentalement les exigences d’intégration par rapport à la version précédente. La modification des modèles de domaines d’activité, la refonte des flux fonctionnels ou la modification des modèles de ressources API sont tous considérés comme des modifications majeures. Les modifications apportées à une version majeure sont rares et nécessitent généralement un cycle de dépréciation prolongé (~2 ans) des versions antérieures pour permettre à tous les utilisateurs de l’API de s’adapter.
Rétrocompatibilité
Votre intégration doit prendre en compte les modifications rétrocompatibles suivantes afin de ne pas être interrompue lorsque des champs supplémentaires sont ajoutés à l’API.
Qu’est-ce qui est considéré comme une modification rétrocompatible?
- Ajout de ressources API ou ajout de nouvelles propriétés à des ressources API existantes
- Modification de l’ordre des paramètres ou des éléments d’un objet JSON
- Ajout de paramètres de requête facultatifs aux méthodes de l’API
- Ajout d’un type d’événement de webhook
Qu’est-ce qui est considéré comme une modification non rétrocompatible?
- Suppression d’une ressource API
- Suppression de l’attribut d’objet d’une ressource API
- Modification des paramètres requis ou des éléments de l’objet JSON
- Suppression des appels d’API précédemment pris en charge