Dernière mise à jour : 31 janvier 2024
Remarque importante : la langue officielle de tous les contrats et autres documents juridiques de Tulip est l'anglais, qui prévaut sur toute autre langue utilisée dans un document traduit.
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 largement les domaines fonctionnels du produit Tulip (par exemple Apps, Automations, Utilisateurs, etc.). Chaque espace de noms d'API se voit attribuer un label appelé sa version (de la forme "v1", "v2", "v3", etc.). Tous les points d'extrémité 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 plateforme Tulip et seront décrites dans les notes de version 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). Tous 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 de 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 de Tulip , un changement est généralement considéré comme rétrocompatible s'il 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 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é.
Corriger une vulnérabilité de sécurité par tous les moyens nécessaires, y compris avec des changements qui seraient autrement considérés 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.
Occasionnellement, Tulip peut avoir besoin de publier une modification d'une API qui n' est pas rétrocompatible. C'est ce que l'on appelle un changement de rupture ou un changement rétro-compatible. Tulip ne publiera que les changements de rupture pour les 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 incluent (à titre d'exemple uniquement) :
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, elles ne sont pas considérées comme faisant partie de l'API stable et peuvent changer à 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 de 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 un support pour ses API qui est similaire au support que nous fournissons pour les autres produits Tulip . Le support complet 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 corrections de sécurité pour ces API. Tulip ne fournit pas de support pour les API non documentées. Le niveau de support que Tulip fournit pour une version de l'espace de nommage de l'API publique varie en fonction de la façon dont elle est étiquetée dans la documentation de l'API :
Alpha - Tulip fournira un support limité pour cette API et peut à tout moment apporter des modifications importantes à cette API.
Bêta - Tulip supporte entièrement cette API, mais peut à tout moment apporter des modifications à cette API. Nous communiquerons ces changements aux clients Bêta.
Stable - Tulip soutient pleinement 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 futur proche. Tulip fournira un support complet pour 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 corrections critiques de sécurité ou de bogues.
Fin du support - Tulip ne fournira plus de support 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 publication 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.