使う

共通ルール

基盤APIを使うときに、どの操作でも共通して守るルールです。APIの系列（v1とv2）の選び方、検索の方法、レートの上限、認可の条件の読み方、再送の方式を説明します。用語は、用語集にもあります。

v1とv2の選び方

基盤APIには、v1とv2の2つの系列があります。パスの先頭が/v1か/v2かで、見分けられます。系列ごとに、扱える対象が違います。

v1の表や既存のケース（ジョブ）を、パスをv2に変えて、そのまま使うことはできません。移行には、専用のAPI（/v2/data-migrationsなど）を使います。データが自動で移行される、または同じデータを共有できる、とは考えないでください。利用している保存先と、アプリの契約を確認してください。

検索とページング

表の行を検索するとき、v1とv2の通常の検索は、次の項目を使います。

列が検索できるかどうかは、definition（表の定義）で確認します。任意のSQL、正規表現、OR式は、受け付けません。serviceの検索は、別の契約で、limitとafterを使います。通常の検索のfiltersは、使えません。

続きがあるときは、応答のnext_cursorが入っています。next_cursorがnullになるまで、同じ条件と、返されたcursorで、取得を続けます。

cursorは、受け取ってから5分で使えなくなります。表の内容や権限が変わったときも、使えなくなります。CURSOR_STALEが返ったら、それまでに集めたページを捨てて、最初から検索し直します。古いページと新しいページを、同じ画面で混ぜないでください。v2の一覧やごみ箱には、afterとnext_afterを使うものがあります。画像には、offsetを使うものがあります。各操作のschemaを優先してください。

変更の監視とレート

変更の監視（changes）は、一定の間隔で、更新の有無を問い合わせる方式です。サーバーから通知が届く方式（SSE）では、ありません。関連・所属の変更イベントの取得も、HTTPでcursorを送り、メタデータだけのイベント、has_more、次のcursorを受け取ります。更新された行の内容は、現在の権限で、改めて取得します。

リクエストの頻度には、次の制限があります。

• 表とアプリの操作は、同時に2リクエストまでです。
• serviceは、同時に2リクエストまでと、承認されたrpm（1分あたりの上限。1〜120）です。
• すべての操作に共通の、固定の上限は、定めていません。利用環境側の制限があり、429が返ることがあります。

429が返ったときは、Retry-Afterがあれば、その時間だけ待ちます。なければ、待つ間隔を延ばし、回数の上限を決めて、再試行します。詳しくは、エラーと再試行にあります。

認可の条件の読み方

OpenAPIの各操作には、x-required-authorityがあり、その操作を実行できる条件が書かれています。次の項目に分かれています。

• 主体（利用者またはservice）
• MFAが必要か
• 認証の鮮度（どれだけ最近、認証したか）
• 必要な権限
• 資源ごとの確認（表、列、行など）

必要な権限が空のときも、誰でも実行できる、という意味ではありません。管理者の権限や、表・行・列の権限は、資源ごとの確認の項目に、別に書かれています。

max_authentication_age_secondsがnullのときは、その操作に固有の、再認証の時間の上限がない、という意味です。トークン、セッション、権限の有効期限を、無視してよいという意味ではありません。画像の操作は、親の資源の読み取りの権限に、判断を任せます。そのため、binding_rulesで、条件が異なります。

再送の方式

通信が途切れたときに、同じ操作をもう一度送ってよいかは、操作によって違います。GET以外のメソッドでも、変更の操作とは限りません。検索、集計、計画のPOSTは、読み取りまたは計画の操作です。

再送のキー（Idempotency-Key）の保持期間は、定めていません。保証として扱わないでください。キーが紐づく範囲は、APIごとに違います。ヘッダーの定義と、各操作のx-retry-policyに従います。service申請のIdempotency-Keyは、UUIDが必須で、申請そのものの識別子になります。他のAPIの、8〜128文字のキーは、応答を再生するためのキーで、同じ意味ではありません。版（version）だけで、競合を検査する管理操作もあります。結果が不明なときは、同じキー、同じ本文、同じ前提を保持して、再送します。版だけを更新して、再送しないでください。新しい論理の操作には、新しいキーを使います。

移行の開始や、旧台帳の採用は、migration_idと、元の本文・fingerprintで、既存の結果を確認します。各操作のx-retry-policyに、方式、識別子、結果の確認の方法があります。次の表は、Idempotency-Key以外の方式で再送を管理する操作（workspace.importを含む）と、結果が不明なときの確認の方法です。