Zuletzt aktualisiert: Januar 31, 2024
Tulip bietet eine Reihe von öffentlichen APIs , die es Benutzern ermöglichen, programmatisch mit der Plattform Tulip zu interagieren. Tulip organisiert seine APIs in Gruppen, die Namespaces genannt werden und im Großen und Ganzen Funktionsbereiche des Produkts Tulip repräsentieren (z.B. Apps, Automationen, Benutzer usw.). Jeder API-Namensraum erhält eine Bezeichnung, die als Version bezeichnet wird (in der Form "v1", "v2", "v3", usw.). Alle API-Endpunkte, die in einem Namespace enthalten sind, werden gemeinsam als Einheit versioniert.
Wenn Tulip neue Funktionen entwickelt, bestehende Funktionen verbessert und Probleme behebt, können wir Updates für diese APIs veröffentlichen, die entweder eine bestehende Version der API ändern oder eine neue Version der API einführen (die Regeln, die vorschreiben, welche Arten von Änderungen eine neue Version erfordern, sind im Abschnitt Stabilität beschrieben). API-Updates werden mit jeder Tulip Plattformversion veröffentlicht und in den Versionshinweisen von Tulipbeschrieben. Es können jederzeit mehrere Versionen eines bestimmten Namespace verfügbar sein. Die Benutzer werden aufgefordert, die aktuellste Version der APIs zu verwenden, frühere Versionen werden jedoch für eine gewisse Zeit beibehalten (weitere Informationen über den Lebenszyklus von Versionen finden Sie im Abschnitt Support ). Alle Rechte zur Nutzung der Tulip APIs sind in der API-Lizenzvereinbarung vonTulip festgelegt.
Stabilität
Wenn eine Version eines Tulip API-Namensraums als stabil angesehen wird, kann Tulip Änderungen an der API veröffentlichen, aber diese Änderungen müssen abwärtskompatibel sein. Im Zusammenhang mit Tulip APIs gilt eine Änderung im Allgemeinen als abwärtskompatibel, wenn sie die Funktionalität bestehender Integrationen, die diese API verwenden, nicht beeinträchtigt. Insbesondere die folgenden Arten von Änderungen werden als abwärtskompatibel angesehen:
Hinzufügen eines neuen Endpunkts zu einem Namespace.
Hinzufügen eines optionalen Feldes im Anfragekörper, eines Abfrageparameters oder eines HTTP-Headers, so dass die Bedeutung anderer Felder, Parameter oder Header unverändert bleibt, wenn das optionale Feld weggelassen wird. Beachten Sie, dass nicht erkannte Felder von Anfragekörpern in der Regel ignoriert werden. Ein Feld, das zuvor keine Bedeutung hatte (was keinen Fehler verursachen würde), kann also in einer späteren Version an Bedeutung gewinnen, ohne dass dies als ein Bruch angesehen wird.
Hinzufügen eines akzeptierten Inhaltstyps des Anfragekörpers zu einem Endpunkt. Handelt es sich bei dem neuen Inhaltstyp um strukturierte Daten (JSON, YAML, CSV usw.), muss er sich an die dokumentierte Struktur des Anfragekörpers halten. Handelt es sich bei dem neuen Inhaltstyp um unstrukturierte Daten (Bild, Video, PDF, reiner Text, andere Binärdaten), muss er sich an alle dokumentierten Einschränkungen in der Beschreibung des Anfragekörpers halten.
Änderung des Typs oder der Validierungsregeln eines Feldes im Anfragekörper, eines Abfrageparameters oder eines HTTP-Headers, so dass alle zuvor gültigen Werte weiterhin als gültig gelten.
Hinzufügen eines neuen Antworttextfeldes oder HTTP-Headers.
Hinzufügen eines neuen HTTP-Statuscodes für Fehlerantworten (4xx, 5xx).
Entfernen möglicher Werte aus dem Typ eines Antwortkörperfeldes oder HTTP-Headers, so dass die Bedeutung anderer Felder oder Antwort-Header unverändert bleibt.
Änderung der Dokumentation eines Typs, eines Fehlercodes, eines Felds oder eines Endpunkts in einer Weise, die das Verhalten der API nicht beeinflusst.
Ändern Sie den Text der Fehlerbeschreibung in den Fehlerantworten.
Ändern der Anzeigenamen oder anderer Textinhalte von Tulip-definierten Ressourcen.
Ändern von Raten-, Größen- oder Ressourcenbeschränkungen, die für Endpunkte gelten.
Behebung eines Fehlers, um das tatsächliche Verhalten eines Endpunkts mit seinem dokumentierten Verhalten in Einklang zu bringen.
Behebung einer Sicherheitslücke mit allen erforderlichen Mitteln, auch mit Änderungen, die andernfalls als störend angesehen würden. Für den Fall, dass Tulip eine kritische Sicherheitslücke beheben muss, die zu einer bahnbrechenden API-Änderung führt, werden wir versuchen, mit unseren Kunden zusammenzuarbeiten, um ihre Integrationen zu aktualisieren und Ausfallzeiten so weit wie möglich zu vermeiden.
Hinzufügen, Entfernen oder Ändern von Endpunkten, Parametern oder Typen, die nicht öffentlich dokumentiert sind.
Gelegentlich kann es vorkommen, dass Tulip eine Änderung an einer API veröffentlichen muss, die nicht rückwärtskompatibel ist. Dies wird als abbrechende Änderung oder abwärtsinkompatible Änderung bezeichnet. Tulip wird abbrechende Änderungen an stabilen APIs nur in einer neuen Version seines API-Namensraums veröffentlichen (mit Ausnahme von kritischen Sicherheitsbehebungen, wie oben beschrieben). Die folgenden Arten von Änderungen werden als abwärtsinkompatibel betrachtet:
Entfernen eines Endpunkts aus einem Namespace.
Entfernen eines Feldes im Anfragekörper, eines Abfrageparameters oder eines HTTP-Headers.
Entfernen eines akzeptierten Body-Inhaltstyps einer Anfrage von einem Endpunkt.
Ändern des Content-Typs des Antwortkörpers eines Endpunkts.
Änderung des Typs oder der Validierungsregeln eines Feldes im Anfragekörper, eines Abfrageparameters oder eines HTTP-Headers, so dass einige Eingaben nicht mehr als gültig angesehen werden.
Ändern Sie den Standardwert eines optionalen Feldes im Anfragekörper, eines Abfrageparameters oder eines HTTP-Headers.
Hinzufügen eines erforderlichen Feldes im Anfragekörper, eines Abfrageparameters oder eines HTTP-Headers.
Hinzufügen eines optionalen Feldes des Anfragekörpers, eines Abfrageparameters oder eines HTTP-Headers, so dass die Bedeutung anderer Felder, Parameter oder Header ebenfalls geändert wird.
Hinzufügen möglicher Werte zum Typ eines Antwortkörperfeldes oder HTTP-Headers.
Hinzufügen eines neuen HTTP-Statuscodes für Erfolgsmeldungen (1xx, 2xx, 3xx).
Entfernen eines Antworttextfeldes oder HTTP-Headers.
Signifikante Änderung der dokumentierten Semantik oder Funktionalität eines Endpunkts, selbst wenn die Schnittstelle unverändert bleibt.
Grenzwerte
Die Tulip API setzt verschiedene Arten von Limits durch, um gemeinsam genutzte Ressourcen (API-Server, Datenbanken usw.) vor übermäßiger Belastung zu schützen, die die Servicequalität für andere Benutzer und Kunden beeinträchtigen kann. Zu diesen Beschränkungen gehören (dies sind nur Beispiele):
Ratenbeschränkungen: Standardmäßig kann ein bestimmter Client nicht mehr als eine bestimmte Anzahl von Anfragen pro Sekunde an einen bestimmten Endpunkt stellen.
Größenbeschränkungen: Der Name einer Ressource darf eine bestimmte Anzahl von Zeichen nicht überschreiten, oder die Größe einer hochgeladenen Datei darf eine bestimmte Dateigröße nicht überschreiten.
Beschränkung der Ressourcenanzahl: Es kann nicht mehr als eine bestimmte Anzahl von Arbeitsbereichen erstellt werden.
Auch wenn Tulip eine Dokumentation zu einigen dieser Beschränkungen bereitstellt, werden diese nicht als Teil der stabilen API betrachtet und können sich jederzeit aufgrund aktueller Lastbedingungen, sich entwickelnder Produktanforderungen, Benutzerpräferenzen und anderer Faktoren ändern. Clients sollten die von Tulip bereitgestellten API-Antworten (Statuscodes, Fehlercodes und Fehlerfelder) verwenden, um Begrenzungsfehler zu behandeln. Tulip behält sich das Recht vor, Clients zu deaktivieren, die diese Begrenzungen wiederholt missachten.
Unterstützen Sie
Tulip bietet Support für seine APIs, der dem Support für andere Tulip Produkte ähnelt. Der vollständige Support umfasst die Pflege der Dokumentation, die Beantwortung von Fragen, die Behebung von Problemen, die Veröffentlichung von Fehlerbehebungen und die Veröffentlichung von Sicherheitskorrekturen für diese APIs. Tulip bietet keinen Support für undokumentierte APIs. Der Grad des Supports, den Tulip für eine öffentliche API-Namespace-Version bietet, hängt davon ab, wie sie in der API-Dokumentation gekennzeichnet ist:
Alpha - Tulip bietet begrenzte Unterstützung für diese API und kann jederzeit Änderungen an dieser API veröffentlichen.
Beta - Tulip unterstützt diese API vollständig, kann aber jederzeit Änderungen an dieser API vornehmen. Wir werden Beta-Kunden über alle Änderungen informieren.
Stabil - Tulip unterstützt diese API vollständig und hält sie für stabil, wie im Abschnitt Stabilität definiert.
Veraltet - Tulip beabsichtigt, diese API in naher Zukunft zu entfernen. Tulip wird volle Unterstützung für diese API bieten, aber Benutzer sollten planen, alle Integrationen, die sie verwenden, auf eine neuere Version der API zu aktualisieren, für die Tulip eine Anleitung bereitstellen wird. Veraltete APIs erhalten in der Regel keine Updates außer kritischen Sicherheits- oder Fehlerbehebungen.
Ende des Supports - Tulip bietet keinen Support mehr für diese API, einschließlich kritischer Sicherheitskorrekturen. Nicht unterstützte APIs können jederzeit und ohne Vorankündigung eingestellt werden.
Stabile API-Namensräume bleiben mindestens einen LTS-Versionszyklus lang stabil, bevor sie als veraltet gekennzeichnet werden. Veraltete API-Namensräume werden noch mindestens zwei LTS-Versionszyklen lang unterstützt, bevor sie als nicht mehr unterstützt gekennzeichnet werden.