Richtlinie zur öffentlichen API

Zuletzt aktualisiert: 31. Januar 2024

Wichtiger Hinweis: Die offizielle Sprache aller Verträge von „ Tulip “ und anderer rechtlicher Dokumente ist Englisch; diese hat Vorrang vor jeder anderen Sprache, die in übersetzten Dokumenten verwendet wird.

Tulip bietet eine Reihe öffentlicher APIs, die es Benutzern ermöglichen, programmgesteuert mit der Plattform „ Tulip “ zu interagieren. Tulip gliedert seine APIs in Gruppen, sogenannte Namespaces, die im Großen und Ganzen die Funktionsbereiche des Produkts „ Tulip “ abbilden (z. B. „ Apps “, „Automations“, „Users“ usw.). Jeder API-Namespace erhält eine Bezeichnung, die als Version bezeichnet wird (in der Form „v1“, „v2“, „v3“ usw.). Alle in einem Namespace enthaltenen API-Endpunkte werden gemeinsam als Einheit versioniert.

Da Tulip neue Funktionen entwickelt, bestehende Funktionen verbessert und Probleme behebt, veröffentlichen wir möglicherweise Updates für diese APIs, die entweder eine bestehende Version der API ändern oder eine neue Version der API einführen (die Regeln, die festlegen, welche Arten von Änderungen eine neue Version erfordern, sind im Abschnitt „Stabilität“ beschrieben). API-Updates werden mit jeder Veröffentlichung der Tulip -Plattform veröffentlicht und in den Versionshinweisen unter Tulipbeschrieben. Zu jedem Zeitpunkt können mehrere Versionen eines bestimmten Namensraums verfügbar sein. Benutzern wird empfohlen, die aktuellste Version der APIs zu verwenden, jedoch werden frühere Versionen für einen bestimmten Zeitraum weiter gepflegt (weitere Informationen zum Lebenszyklus von Versionen finden Sie im Abschnitt „Support“ ). Alle Rechte zur Nutzung der APIs unter Tulip sind in der API-Lizenzvereinbarung unterTulip festgelegt.

Stabilität

Wenn eine Version eines „ Tulip “-API-Namespace als stabil gilt, kann Tulip Änderungen an der API veröffentlichen; diese Änderungen müssen jedoch abwärtskompatibel sein. Im Zusammenhang mit den „ Tulip “-APIs gilt eine Änderung im Allgemeinen als abwärtskompatibel, wenn sie die Funktionalität bestehender Integrationen, die diese API nutzen, nicht beeinträchtigt. Insbesondere gelten die folgenden Arten von Änderungen als abwärtskompatibel:

  • Hinzufügen eines neuen Endpunkts zu einem Namespace.
  • Hinzufügen eines optionalen Feldes im Request-Body, eines Abfrageparameters oder eines HTTP-Headers, sodass die Bedeutung anderer Felder, Parameter oder Header unverändert bleibt, wenn das optionale Feld weggelassen wird. Beachten Sie, dass nicht erkannte Felder im Request-Body in der Regel ignoriert werden, sodass ein Feld, das zuvor keine Bedeutung hatte (was keinen Fehler verursachen würde), in einer späteren Version eine Bedeutung erhalten kann, ohne dass dies als kompatibilitätsbrechende Änderung angesehen wird.
  • Hinzufügen eines akzeptierten Content-Types für den Request-Body zu einem Endpunkt. Wenn der neue Content-Type strukturierte Daten darstellt (JSON, YAML, CSV usw.), muss er der dokumentierten Struktur des Request-Bodys entsprechen. Wenn es sich bei dem neuen Content-Type um unstrukturierte Daten handelt (Bild, Video, PDF, Klartext, sonstige Binärdaten), muss er allen in der Beschreibung des Request-Bodys dokumentierten Einschränkungen entsprechen.
  • Änderung des Typs oder der Validierungsregeln eines Feldes im Request-Body, eines Abfrageparameters oder eines HTTP-Headers, sodass alle zuvor gültigen Werte weiterhin als gültig gelten.
  • Hinzufügen eines neuen Felds im Antworttext oder eines neuen HTTP-Headers.
  • Hinzufügen eines neuen HTTP-Statuscodes für Fehlerantworten (4xx, 5xx).
  • Entfernen möglicher Werte aus dem Typ eines Feldes im Antworttext oder eines HTTP-Headers, sodass die Bedeutung anderer Felder oder Antwort-Header unverändert bleibt.
  • Änderung der Dokumentation eines Typs, eines Fehlercodes, eines Feldes oder eines Endpunkts, ohne dass dies Auswirkungen auf das Verhalten der API hat.
  • Änderung des Wortlauts der Fehlerbeschreibung, die in Fehlerantworten angezeigt wird.
  • Änderung der Anzeigenamen oder anderer Textinhalte von Ressourcen, die in „ Tulip “ definiert sind.
  • Änderung der für Endpunkte geltenden Grenzwerte für Raten, Größen oder die Anzahl der Ressourcen.
  • 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, einschließlich Änderungen, die andernfalls als inkompatibel gelten würden. Falls Tulip einen kritischen Sicherheitspatch veröffentlichen muss, der zu einer inkompatiblen API-Änderung führt, werden wir versuchen, gemeinsam mit unseren Kunden deren Integrationen anzupassen, um 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 abwärtskompatibel ist. Dies wird als „Breaking Change“ oder als „abwärtsinkompatible Änderung“ bezeichnet. Tulip veröffentlicht abwärtsinkompatible Änderungen an stabilen APIs ausschließlich in einer neuen Version seines API-Namensraums (mit Ausnahme kritischer Sicherheitskorrekturen, wie oben beschrieben). Die folgenden Arten von Änderungen gelten als abwärtsinkompatibel:

  • Einen Endpunkt aus einem Namespace entfernen.
  • Entfernen eines Felds aus dem Request-Body, eines Abfrageparameters oder eines HTTP-Headers.
  • Entfernen eines akzeptierten Content-Types des Anforderungsinhalts aus einem Endpunkt.
  • Ändern des Content-Types des Antworttextes eines Endpunkts.
  • Änderung des Typs oder der Validierungsregeln eines Feldes im Request-Body, eines Abfrageparameters oder eines HTTP-Headers, sodass bestimmte Eingaben nicht mehr als gültig angesehen werden.
  • Ändern des Standardwerts eines optionalen Felds im Request-Body, eines Abfrageparameters oder eines HTTP-Headers.
  • Hinzufügen eines obligatorischen Feldes im Request-Body, eines Abfrageparameters oder eines HTTP-Headers.
  • Das Hinzufügen eines optionalen Felds im Request-Body, eines Abfrageparameters oder eines HTTP-Headers, wodurch sich auch die Bedeutung anderer Felder, Parameter oder Header ändert.
  • Hinzufügen möglicher Werte zum Typ eines Feldes im Antworttext oder eines HTTP-Headers.
  • Hinzufügen eines neuen HTTP-Statuscodes für eine erfolgreiche Antwort (1xx, 2xx, 3xx).
  • Ein Feld im Antworttext oder einen HTTP-Header entfernen.
  • Die dokumentierte Semantik oder Funktionalität eines Endpunkts wesentlich zu verändern, auch wenn die Schnittstelle unverändert bleibt.

Grenzen

Die „ Tulip “-API wendet verschiedene Arten von Beschränkungen an, um gemeinsam genutzte Ressourcen (API-Server, Datenbanken usw.) vor einer übermäßigen Belastung zu schützen, die sich auf die Servicequalität für andere Nutzer und Kunden auswirken könnte. Zu diesen Beschränkungen gehören unter anderem (dies sind lediglich Beispiele):

  • Ratenbegrenzungen: Standardmäßig darf ein bestimmter Client nicht öfter als eine bestimmte Anzahl von Malen pro Sekunde Anfragen an einen bestimmten Endpunkt senden.
  • Größenbeschränkungen: Der Name einer Ressource darf eine bestimmte Zeichenanzahl nicht überschreiten, bzw. die Größe einer hochgeladenen Datei darf eine bestimmte Dateigröße nicht überschreiten.
  • Beschränkungen hinsichtlich der Anzahl der Ressourcen: Es können nicht mehr als eine bestimmte Anzahl von Arbeitsbereichen erstellt werden.

Zwar finden sich unter Tulip möglicherweise Informationen zu einigen dieser Beschränkungen, diese gelten jedoch nicht als Teil der stabilen API und können sich jederzeit ändern – abhängig von der aktuellen Auslastung, sich ändernden Produktanforderungen, Nutzerpräferenzen und anderen Faktoren. Clients sollten die in den API-Antworten von Tulip bereitgestellten Informationen (Statuscodes, Fehlercodes und Fehlerfelder) nutzen, um Fehler im Zusammenhang mit Beschränkungen zu behandeln. Tulip behält sich das Recht vor, Clients zu sperren, die diese Beschränkungen wiederholt missachten.

Support

Tulip bietet Support für seine APIs, der dem Support ähnelt, den wir für andere Produkte von Tulip bereitstellen. Der umfassende Support umfasst die Pflege der Dokumentation, die Beantwortung von Fragen, die Fehlerbehebung, die Veröffentlichung von Fehlerbehebungen sowie die Veröffentlichung von Sicherheitsupdates für diese APIs. Tulip bietet keinen Support für undokumentierte APIs. Der Umfang des Supports, den Tulip für eine öffentliche API-Namespace-Version bereitstellt, hängt davon ab, wie diese in der API-Dokumentation gekennzeichnet ist:

  • Alpha – Tulip bietet nur eingeschränkten Support für diese API und behält sich vor, jederzeit Änderungen an dieser API vorzunehmen, die zu Inkompatibilitäten führen können.
  • Beta – Tulip unterstützt diese API vollständig, behält sich jedoch vor, jederzeit kompatibilitätsbrechende Änderungen an dieser API vorzunehmen. Wir werden Beta-Kunden über alle kompatibilitätsbrechenden Änderungen informieren.
  • Stabil – Tulip unterstützt diese API vollständig und stuft sie gemäß der Definition im Abschnitt „Stabilität“ als stabil ein.
  • Veraltet – Tulip beabsichtigt, diese API in naher Zukunft zu entfernen. Tulip wird diese API vollständig unterstützen; Nutzer sollten jedoch planen, alle Integrationen, die diese API nutzen, auf eine neuere Version der API zu aktualisieren. Tulip bietet hierzu eine Anleitung. Veraltete APIs erhalten in der Regel keine Updates mehr, außer bei kritischen Sicherheits- oder Fehlerbehebungen.
  • Ende des Supports – Tulip bietet keinerlei Support für diese API, einschließlich kritischer Sicherheitskorrekturen. Nicht unterstützte APIs können jederzeit ohne Vorankündigung ihre Funktion einstellen.

Stabile API-Namespaces bleiben mindestens einen LTS-Release-Zyklus lang stabil, bevor sie als veraltet gekennzeichnet werden. Veraltete API-Namespaces werden noch mindestens zwei LTS-Release-Zyklen lang unterstützt, bevor sie als nicht mehr unterstützt gekennzeichnet werden.