Dernière mise à jour : 31 janvier 2024
Tulip fournit un ensemble d'API publiques qui permettent aux utilisateurs d'interagir de manière programmatique avec la plateforme Tulip . Tulip organise ses API en groupes appelés " Namespaces" qui représentent globalement les domaines fonctionnels du produit Tulip (par exemple Apps, Automations, Utilisateurs, etc.). Chaque espace de noms d'API se voit attribuer une étiquette appelée " version " (de la forme "v1", "v2", "v3", etc.). Tous les points de terminaison de l'API contenus dans un espace de noms sont versionnés ensemble en tant qu'unité.
Au fur et à mesure que Tulip développe de nouvelles fonctionnalités, améliore les fonctionnalités existantes et corrige les problèmes, nous pouvons publier des mises à jour de ces API qui modifient une version existante de l'API ou introduisent une nouvelle version de l'API (les règles qui dictent quels types de changements nécessitent une nouvelle version sont décrites dans la section " Stabilité "). Les mises à jour de l'API sont publiées avec chaque version de la plate-forme Tulip et sont décrites dans les notes de mise à jour de Tulip. Plusieurs versions d'un espace de nommage donné peuvent être disponibles à tout moment. Les utilisateurs sont encouragés à utiliser la version la plus récente des API, mais les versions précédentes sont maintenues pendant un certain temps (voir la section Support pour plus d'informations sur le cycle de vie des versions). Les droits d'utilisation des API de Tulip sont définis dans l'accord de licence API deTulip.
Stabilité
Lorsqu'une version d'un espace de noms d'API Tulip est considérée comme stable, Tulip peut publier des modifications de l'API, mais ces modifications doivent être rétrocompatibles. Dans le contexte des API Tulip , une modification est généralement considérée comme rétrocompatible si elle n'interrompt pas la fonctionnalité des intégrations existantes utilisant cette API. Plus précisément, les types de modifications suivants sont considérés comme rétrocompatibles :
Ajout d'un nouveau point de terminaison à un espace de nommage.
Ajout d'un champ facultatif dans le corps de la requête, d'un paramètre de requête ou d'un en-tête HTTP, de sorte que la signification des autres champs, paramètres ou en-têtes reste inchangée lorsque le champ facultatif est omis. Notez que les champs non reconnus des corps de requête sont généralement ignorés, de sorte qu'un champ qui n'avait auparavant aucune signification (et qui ne provoquerait pas d'erreur) peut devenir significatif dans une version ultérieure sans que cela soit considéré comme un changement radical.
Ajout d'un type de contenu accepté dans le corps de la demande à un point de terminaison. Si le nouveau type de contenu représente des données structurées (JSON, YAML, CSV, etc.), il doit respecter la structure documentée du corps de la demande. Si le nouveau type de contenu représente des données non structurées (image, vidéo, PDF, texte brut, autres données binaires), il doit respecter toutes les contraintes documentées dans la description du corps de la demande.
Modification du type ou des règles de validation d'un champ du corps de la requête, d'un paramètre de la requête ou d'un en-tête HTTP de telle sorte que toutes les valeurs précédemment valides soient encore considérées comme valides.
Ajout d'un nouveau champ du corps de la réponse ou d'un en-tête HTTP.
Ajout d'un nouveau code d'état HTTP de réponse d'erreur (4xx, 5xx).
Suppression des valeurs possibles du type d'un champ du corps de la réponse ou d'un en-tête HTTP, de sorte que la signification des autres champs ou en-têtes de la réponse reste inchangée.
Modification de la documentation d'un type, d'un code d'erreur, d'un champ ou d'un point de terminaison d'une manière qui n'affecte pas le comportement de l'API.
Modification du texte de la description de l'erreur présentée dans les réponses à l'erreur.
Modifier les noms d'affichage ou tout autre contenu textuel de toute ressource définie par Tulip.
Modification des limites de débit, de taille ou de nombre de ressources appliquées aux points d'extrémité.
Correction d'un bogue afin d'aligner le comportement réel d'un point de terminaison sur son comportement documenté.
La correction d'une faille de sécurité par tous les moyens nécessaires, y compris par des modifications qui seraient autrement considérées comme des ruptures. Dans le cas où Tulip doit publier un correctif de sécurité critique qui entraîne une modification de l'API, nous essaierons de travailler avec nos clients pour mettre à jour leurs intégrations afin d'éviter autant que possible les temps d'arrêt.
l'ajout, la suppression ou la modification de points finaux, de paramètres ou de types qui ne sont pas documentés publiquement.
Il peut arriver que Tulip doive publier une modification d'une API qui n' est pas rétrocompatible. C'est ce qu'on appelle une modification de rupture ou une modification rétrocompatible. Tulip ne publiera que les modifications de rupture des API stables dans une nouvelle version de son API Namespace (à l'exception des correctifs de sécurité critiques, comme décrit ci-dessus). Les types de modifications suivants sont considérés comme rétrocompatibles :
Suppression d'un point de terminaison d'un espace de nommage.
Suppression d'un champ du corps de la requête, d'un paramètre de requête ou d'un en-tête HTTP.
Suppression d'un type de contenu de requête accepté d'un point de terminaison.
Modifier le type de contenu du corps de la réponse d'un point de terminaison.
Modification du type ou des règles de validation d'un champ du corps de la requête, d'un paramètre de la requête ou d'un en-tête HTTP, de sorte que certaines entrées ne sont plus considérées comme valides.
Modification de la valeur par défaut d'un champ facultatif du corps de la requête, d'un paramètre de requête ou d'un en-tête HTTP.
Ajout d'un champ du corps de la requête, d'un paramètre de requête ou d'un en-tête HTTP requis.
Ajout d'un champ facultatif du corps de la requête, d'un paramètre de la requête ou d'un en-tête HTTP de telle sorte que la signification de tous les autres champs, paramètres ou en-têtes est également modifiée.
Ajout de valeurs possibles au type d'un champ du corps de la réponse ou d'un en-tête HTTP.
Ajout d'un nouveau code d'état HTTP de réponse positive (1xx, 2xx, 3xx).
Suppression d'un champ du corps de la réponse ou d'un en-tête HTTP.
Modification significative de la sémantique ou de la fonctionnalité documentée d'un point d'accès, même si l'interface reste inchangée.
Limites
L'API Tulip applique différents types de limites afin de protéger les ressources partagées (serveurs API, bases de données, etc.) d'une charge excessive qui peut avoir un impact sur la qualité du service pour les autres utilisateurs et les autres clients. Ces limites sont les suivantes (il ne s'agit que d'exemples illustratifs) :
Limites de débit: Par défaut, un client donné ne peut pas adresser de demandes à un point d'accès donné plus d'un certain nombre de fois par seconde.
Limites de taille: Le nom d'une ressource ne peut dépasser un certain nombre de caractères, ou la taille d'un fichier téléchargé ne peut dépasser une certaine taille de fichier.
Limites du nombre de ressources: Il n'est pas possible de créer plus d'un certain nombre d'espaces de travail.
Bien que Tulip puisse fournir de la documentation sur certaines de ces limites, celles-ci ne sont pas considérées comme faisant partie de l'API stable et peuvent être modifiées à tout moment en fonction des conditions de charge actuelles, de l'évolution des exigences du produit, des préférences de l'utilisateur et d'autres facteurs. Les clients doivent utiliser les informations fournies par les réponses de l'API Tulip (codes d'état, codes d'erreur et champs d'erreur) pour gérer les erreurs de limitation. Tulip se réserve le droit de désactiver les clients qui ne respectent pas ces limites de manière répétée.
Soutien
Tulip fournit une assistance pour ses API qui est similaire à l'assistance que nous fournissons pour d'autres produits Tulip . L'assistance complète comprend la maintenance de la documentation, la réponse aux questions, la résolution des problèmes, la publication des corrections de bogues et des correctifs de sécurité pour ces API. Tulip ne fournit pas d'assistance pour les API non documentées. Le niveau d'assistance fourni par Tulip pour une version de l'espace de nommage de l'API publique varie en fonction de la manière dont elle est étiquetée dans la documentation de l'API :
Alpha - Tulip fournira une assistance limitée pour cette API et pourra à tout moment apporter des modifications importantes à cette API.
Bêta - Tulip prend entièrement en charge cette API, mais peut à tout moment apporter des modifications à cette API. Nous communiquerons ces modifications aux clients de la version bêta.
Stable - Tulip prend entièrement en charge cette API et la considère comme stable, comme défini dans la section Stabilité.
Déclassé - Tulip a l'intention de supprimer cette API dans un avenir proche. Tulip assurera une prise en charge complète de cette API, mais les utilisateurs doivent prévoir de mettre à jour toutes les intégrations qui l'utilisent vers une version plus récente de l'API, pour laquelle Tulip fournira des conseils. Les API obsolètes ne recevront généralement pas de mises à jour, à l'exception des correctifs de sécurité ou de bogues critiques.
Fin de l'assistance - Tulip ne fournira aucune assistance pour cette API, y compris les correctifs de sécurité critiques. Les API non prises en charge peuvent cesser de fonctionner à tout moment sans préavis.
Les espaces de noms d'API stables resteront stables pendant au moins un cycle de mise à jour LTS avant d'être marqués comme dépréciés. Les espaces de noms d'API dépréciés resteront pris en charge pendant au moins deux cycles de publication LTS avant d'être marqués comme non pris en charge.