Politique relative aux API publiques
Dernière mise à jour : 31 janvier 2024
Remarque importante : La langue officielle de tous les contrats et autres documents juridiques d’ 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 par programmation avec la plateforme Tulip . Tulip organise ses API en groupes appelés « espaces de noms » (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 » (sous la forme « v1 », « v2 », « v3 », etc.). Tous les points de terminaison d’API contenus dans un espace de noms sont gérés ensemble comme une seule unité.
À mesure qu’ Tulip développe de nouvelles fonctionnalités, améliore celles existantes et corrige des 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 celle-ci (les règles déterminant quels types de modifications nécessitent une nouvelle version sont décrites dans la section « Stabilité » ). Les mises à jour des API sont publiées à chaque nouvelle version de la plateforme Tulip et seront décrites dans les notes de mise à jour disponibles sur Tulip. Plusieurs versions d’un espace de noms donné peuvent être disponibles à tout moment. Les utilisateurs sont invités à utiliser la version la plus récente des API, mais les versions antérieures 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 d’ Tulip sont définis dans le contrat de licence des API disponible à l’adresseTulip.
Stabilité
Lorsqu’une version d’un espace de noms d’API de l’ Tulip est considérée comme stable, Tulip peut publier des modifications apportées à l’API, mais ces modifications doivent être rétrocompatibles. Dans le cadre des API de l’ Tulip , une modification est généralement considérée comme rétrocompatible si elle ne perturbe pas le fonctionnement 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 noms.
- 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 telle sorte que la signification des autres champs, paramètres ou en-têtes reste inchangée lorsque le champ facultatif est omis. Veuillez noter que les champs non reconnus dans le corps des requêtes sont généralement ignorés ; ainsi, un champ qui n’avait auparavant aucune signification (et qui ne provoquait pas d’erreur) peut acquérir une signification dans une version ultérieure sans que cela soit considéré comme une modification rompant la compatibilité.
- Ajout d'un type de contenu autorisé pour le corps de la requête à un point de terminaison. Si le nouveau type de contenu correspond à des données structurées (JSON, YAML, CSV, etc.), il doit respecter la structure documentée du corps de la requête. Si le nouveau type de contenu correspond à 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 requête.
- Modification du type ou des règles de validation d'un champ du corps d'une requête, d'un paramètre de requête ou d'un en-tête HTTP, de manière à ce que toutes les valeurs auparavant valides restent valides.
- Ajout d'un nouveau champ dans le corps de la réponse ou d'un nouvel en-tête HTTP.
- Ajout d'un nouveau code d'état HTTP de réponse d'erreur (4xx, 5xx).
- Supprimer certaines valeurs possibles du type d'un champ du corps d'une réponse ou d'un en-tête HTTP, de manière à ce que la signification des autres champs ou en-têtes de réponse reste inchangée.
- Modifier la documentation d'un type, d'un code d'erreur, d'un champ ou d'un point de terminaison sans que cela n'affecte le comportement de l'API.
- Modification du texte de la description de l'erreur affichée dans les réponses d'erreur.
- Modification des noms d'affichage ou de tout autre contenu textuel des ressources définies par Tulip.
- Modification des limites de fréquence, de taille ou de nombre de ressources appliquées aux terminaux.
- Correction d'un bug visant à aligner le comportement réel d'un point de terminaison sur son comportement tel qu'il est décrit dans la documentation.
- Corriger une faille de sécurité par tous les moyens nécessaires, y compris en apportant des modifications qui seraient normalement considérées comme incompatibles. Si Tulip devait publier un correctif de sécurité critique entraînant une modification incompatible de l'API, nous nous efforcerons de collaborer avec nos clients afin qu'ils mettent à jour leurs intégrations et d'éviter ainsi, dans la mesure du possible, toute interruption de service.
- Ajouter, supprimer ou modifier des points de terminaison, des paramètres ou des types qui ne sont pas documentés publiquement.
Il peut arriver que Tulip soit amené à publier une modification d’une API qui ne soit pas rétrocompatible. On parle alors de « modification rompant la compatibilité » ou de « modification non rétrocompatible ». Tulip ne publiera de modifications rompant la compatibilité pour les API stables que dans une nouvelle version de son espace de noms d’API (à l’exception des correctifs de sécurité critiques, comme décrit ci-dessus). Les types de modifications suivants sont considérés comme non rétrocompatibles :
- Suppression d'un point de terminaison d'un espace de noms.
- Suppression d'un champ du corps d'une requête, d'un paramètre de requête ou d'un en-tête HTTP.
- Suppression du type de contenu du corps d'une requête acceptée au niveau d'un point de terminaison.
- Modification du type de contenu du corps de la réponse d'un point de terminaison.
- Modifier le type ou les règles de validation d'un champ du corps d'une requête, d'un paramètre de requête ou d'un en-tête HTTP, de sorte que certaines entrées ne soient 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 obligatoire dans le corps de la requête, d'un paramètre de requête ou d'un en-tête HTTP.
- Ajouter un champ facultatif dans le corps de la requête, un paramètre de requête ou un en-tête HTTP de telle sorte que la signification de tout autre champ, paramètre ou en-tête soit é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 réussie (1xx, 2xx, 3xx).
- Suppression d'un champ du corps de la réponse ou d'un en-tête HTTP.
- Modifier de manière significative la sémantique ou les fonctionnalités documentées d'un point de terminaison, 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.) contre une charge excessive susceptible d'affecter la qualité de service pour les autres utilisateurs et clients. Ces limites comprennent notamment (il s'agit uniquement d'exemples à titre indicatif) :
- Limites de débit: par défaut, un client donné ne peut pas envoyer plus d'un certain nombre de requêtes par seconde à un point de terminaison donné.
- Limites de taille: le nom d'une ressource ne doit pas dépasser un certain nombre de caractères, et la taille d'un fichier téléchargé ne doit pas dépasser une certaine limite.
- Limites relatives au nombre de ressources: le nombre d'espaces de travail pouvant être créés ne doit pas dépasser un certain seuil.
Bien que le site Tulip puisse fournir des informations sur certaines de ces limites, celles-ci ne sont pas considérées comme faisant partie de l'API stable et sont susceptibles d'évoluer à tout moment en fonction de la charge actuelle, de l'évolution des exigences du produit, des préférences des utilisateurs 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 liées aux limitations. Tulip se réserve le droit de désactiver les clients qui enfreignent de manière répétée ces limites.
Assistance
Tulip offre une assistance pour ses API similaire à celle que nous fournissons pour les autres produits Tulip . Cette assistance complète comprend la mise à jour de la documentation, la réponse aux questions, le dépannage, la publication de correctifs de bogues et la publication de 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 d'espace de noms d'API publique varie en fonction de la manière dont elle est désignée dans la documentation de l'API :
- Alpha - Tulip assurera une prise en charge limitée de cette API et se réserve le droit d'y apporter à tout moment des modifications susceptibles d'entraîner une rupture de compatibilité.
- Beta - Tulip prend entièrement en charge cette API, mais se réserve le droit d'y apporter à tout moment des modifications susceptibles d'entraîner une rupture de compatibilité. Nous informerons les clients de la version bêta de toute modification de ce type.
- Stable — Tulip prend entièrement en charge cette API et la considère comme stable, conformément à la définition donnée dans la section « Stabilité ».
- Obsolète - Tulip prévoit 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 toute intégration l'utilisant vers une version plus récente de l'API ; Tulip fournira des conseils à cet effet. Les API obsolètes ne feront généralement l'objet d'aucune mise à jour, sauf en cas de correctifs de sécurité critiques ou de corrections de bogues.
- Fin du support — Tulip ne fournira plus aucun 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 obsolètes. Les espaces de noms d'API obsolètes continueront d'être pris en charge pendant au moins deux cycles de publication LTS avant d'être marqués comme n'étant plus pris en charge.