公開APIポリシー
最終更新日:2024年1月31日
重要なお知らせ: Tulip のすべての契約書およびその他の法的文書における公用語は英語であり、翻訳文書で使用されている他のいかなる言語よりも優先されるものとします。
Tulip Tulip プラットフォームとプログラムを通じてやり取りできるようにする一連の公開APIを提供しています 。 では、APIをTulip 「ネームスペース」と呼ばれるグループに分類しており、これらは 製品の機能領域(例: 、Automations、Usersなど)を大まかに表しています。各APIネームスペースには、「v1」、「v2」、「v3」などの形式で表される「Tulip Appsバージョン」と呼ばれるラベルが割り当てられています。 あるネームスペースに含まれるすべてのAPIエンドポイントは、1つの単位としてまとめてバージョン管理されます。
Tulip が新機能の開発、既存機能の改善、および問題の修正を行う際、既存のAPIバージョンを変更するか、新しいAPIバージョンを導入する更新をリリースする場合があります(どのような変更が新しいバージョンの必要性を生じさせるかについては、「安定性」のセクションで説明されています)。APIの更新は、Tulip プラットフォームの各リリースに合わせて公開され、Tulipのリリースノートに記載されます。 特定のネームスペースについては、いつでも複数のバージョンが利用可能となる場合があります。ユーザーにはAPIの最新バージョンの使用を推奨しますが、以前のバージョンも一定期間メンテナンスされます(バージョンのライフサイクルに関する詳細は、「サポート」セクションを参照してください)。Tulip APIの使用権限については、Tulipの「APIライセンス契約」に規定されている通りです。
安定性
Tulip API ネームスペースのバージョンが安定版とみなされた場合、Tulip はAPIの変更をリリースすることがありますが、そのような変更は下位互換性を保たなければなりません。Tulip API に関しては、そのAPIを使用している既存の統合機能に支障をきたさない限り、その変更は一般的に下位互換性があるものとみなされます。具体的には、以下の種類の変更が下位互換性があるものとみなされます:
- ネームスペースに新しいエンドポイントを追加する。
- オプションのリクエスト本文フィールド、クエリパラメータ、またはHTTPヘッダーを追加し、そのオプションフィールドが省略された場合でも、他のフィールド、パラメータ、またはヘッダーの意味が変更されないようにする。なお、リクエスト本文の認識されないフィールドは通常無視されるため、以前は意味を持たなかった(エラーを引き起こさなかった)フィールドが、その後のリリースで意味を持つようになる場合でも、互換性を損なう変更とは見なされない。
- エンドポイントに、受け入れ可能なリクエストボディのコンテンツタイプを追加します。新しいコンテンツタイプが構造化データ(JSON、YAML、CSVなど)である場合は、リクエストボディの仕様で規定された構造に従わなければなりません。新しいコンテンツタイプが非構造化データ(画像、動画、PDF、プレーンテキスト、その他のバイナリデータ)である場合は、リクエストボディの説明に記載されている制約に従わなければなりません。
- リクエストボディのフィールド、クエリパラメータ、またはHTTPヘッダーの型や検証ルールを変更する際、それまで有効だった値はすべて引き続き有効とみなされるようにすること。
- 新しいレスポンス本文フィールドまたはHTTPヘッダーを追加する。
- 新しいエラー応答のHTTPステータスコード(4xx、5xx)を追加します。
- レスポンス本文フィールドまたはHTTPヘッダーの型から、可能な値を削除すること。ただし、他のフィールドやレスポンスヘッダーの意味は変更されないようにする。
- APIの動作に影響を与えない範囲で、型、エラーコード、フィールド、またはエンドポイントのドキュメントを変更すること。
- エラー応答に表示されるエラー説明のテキストを変更する。
- Tulip で定義されたリソースの表示名やその他のテキストコンテンツを変更すること。
- エンドポイントに適用されているレート、サイズ、またはリソース数の制限を変更する。
- エンドポイントの実際の動作を、ドキュメントに記載された動作と一致させるために、バグを修正する。
- セキュリティの脆弱性を、たとえ通常であれば互換性を損なう変更とみなされるような措置を含め、あらゆる手段を講じて修正します。Tulip が、APIの互換性を損なう変更を伴う重大なセキュリティ修正をリリースする必要が生じた場合、ダウンタイムを可能な限り回避できるよう、お客様と協力して統合機能の更新に取り組んでまいります。
- 公開ドキュメントに記載されていないエンドポイント、パラメータ、または型を追加、削除、または変更すること。
Tulip では、時折、下位互換性のないAPIの変更をリリースする必要が生じる場合があります。これは「破壊的変更」または「下位互換性のない変更」と呼ばれます。Tulip は、安定版APIに対する破壊的変更を、APIネームスペースの新しいバージョンでのみリリースします(前述の重大なセキュリティ修正を除く)。以下の種類の変更は、下位互換性のない変更とみなされます:
- ネームスペースからエンドポイントを削除する。
- リクエストボディのフィールド、クエリパラメータ、またはHTTPヘッダーを削除する。
- エンドポイントから、受理済みのリクエスト本体のコンテンツタイプを削除する。
- エンドポイントのレスポンス本文のコンテンツタイプを変更する。
- リクエストボディのフィールド、クエリパラメータ、またはHTTPヘッダーの型や検証ルールを変更し、一部の入力が有効とみなされなくなるようにすること。
- オプションのリクエストボディフィールド、クエリパラメータ、またはHTTPヘッダーのデフォルト値を変更する。
- 必須のリクエストボディフィールド、クエリパラメータ、またはHTTPヘッダーを追加する。
- オプションのリクエスト本文フィールド、クエリパラメータ、またはHTTPヘッダーを追加することで、他のフィールド、パラメータ、またはヘッダーの意味も変更されてしまうこと。
- レスポンス本文フィールドまたはHTTPヘッダーの型に、取り得る値を追加する。
- 新しい成功応答のHTTPステータスコード(1xx、2xx、3xx)を追加します。
- レスポンス本体のフィールドまたはHTTPヘッダーを削除する。
- インターフェースに変更がない場合でも、エンドポイントの文書化された意味論や機能を大幅に変更すること。
制限
Tulip API では、共有リソース(API サーバー、データベースなど)を過度な負荷から保護し、他のユーザーや顧客のサービス品質への影響を防ぐため、さまざまな制限を設けています。こうした制限には、次のようなものがあります(これらはあくまで一例です):
- レート制限:デフォルトでは、特定のクライアントが特定のエンドポイントに対して1秒あたり一定回数以上リクエストを行うことはできません。
- サイズ制限:リソースの名前は特定の文字数を超えてはならず、また、アップロードするファイルのサイズは特定のファイルサイズを超えてはなりません。
- リソース数の制限:作成できるワークスペースの数は、一定数までとなっています。
Tulip では、これらの制限の一部についてドキュメントが提供されている場合がありますが、これらは安定版 API の一部とはみなされず、現在の負荷状況、製品要件の変化、ユーザーの好み、その他の要因に基づき、いつでも変更される可能性があります。クライアントは、制限に関連するエラーを処理する際、Tulip の API レスポンスで提供される情報(ステータスコード、エラーコード、エラーフィールド)を利用する必要があります。Tulip は、これらの制限を繰り返し無視するクライアントの利用を停止する権利を留保します。
サポート
Tulip Tulip の他の製品と同様に、APIに対するサポートを提供しています。完全なサポートには、ドキュメントの維持管理、質問への回答、問題のトラブルシューティング、バグ修正のリリース、およびこれらのAPIに対するセキュリティ修正のリリースが含まれます。 は、ドキュメント化されていないAPIに対するサポートは提供していません。 がパブリックAPIネームスペースのバージョンに対して提供するサポートのレベルは、APIドキュメントでのラベル付け方法によって異なります:Tulip Tulip
- Alpha-Tulip では、この API に対するサポートは限定的なものとなり、いつでもこの API に対して互換性を損なう変更が導入される可能性があります。
- ベータ版-Tulip はこの API を完全にサポートしていますが、いつでもこの API に対して互換性を損なう変更が導入される可能性があります。互換性を損なう変更がある場合は、ベータ版をご利用のお客様にその旨をお知らせいたします。
- 安定版-Tulip は、この API を完全にサポートしており、「安定性」のセクションで定義されている通り、これを安定版と見なしています。
- 非推奨-Tulip では、近い将来この API を廃止する予定です。Tulip ではこの API を完全にサポートする予定ですが、ユーザーは、この API を使用している統合機能を、Tulip でガイダンスが提供される新しいバージョンの API に更新する計画を立てる必要があります。非推奨の API については、重大なセキュリティ修正やバグ修正を除き、通常は更新が行われません。
- サポート終了-Tulip では、この API に対するサポート(重大なセキュリティ修正を含む)は一切提供されません。サポート対象外の API は、予告なくいつでも動作しなくなる可能性があります。
安定版のAPIネームスペースは、非推奨としてマークされるまで、少なくとも1つのLTSリリースサイクルにわたって安定した状態が維持されます。非推奨のAPIネームスペースは、サポート終了としてマークされるまで、少なくとも2つのLTSリリースサイクルにわたってサポートが継続されます。