最初のリクエスト

新しいアクセストークンからレコードの 1 ページまで。権限を読み、オブジェクトを見つけ、一覧する。そして最初に出る 4 つの拒否を見分けます。

リクエストは 3 つです。クライアントの接続で得たアクセストークンが必要で、以下のパスはすべて /api/v1 を基準にしています。

1. 権限を読む

GET /api/v1/capabilities
Authorization: Bearer <token>

{
  "actions": ["objects.read", "records.read", "records.write"],
  "features": { "api": true, "cpq": true, "approvals": false },
  "revision": 7
}

探りを入れるのではなく、ここから始めてください。 actions は存在する 21 個のうち、このトークンとこのメンバーが実際に許可されているものです。features は 8 つのモジュールの有効・無効の状態です。revision はモジュールポリシーのリビジョンなので、設定が変わったのかレコードが変わったのかを区別できます。

エンドポイント自身の説明が端的に述べています。拒否から権限を推測するのではなく、これをポーリングしてください。403 は何かがおかしいことを伝えますが、capabilities は何を持っているかを伝えます。

2. オブジェクトを見つける

GET /api/v1/objects

各エントリは key、label、kind、所有する moduleKey、revision を持ちます。

予期すべきことが 2 つあります。一覧はあなたのアクセス権でフィルターされます — オブジェクトを読めないメンバーにはそれが見えないため、これはワークスペースの完全なスキーマではありません。そして標準オブジェクトは設置されるまで存在しません。POST /bootstrap が有効なモジュールの所有するものを作成します。まだ誰も設定していないワークスペースでは、この一覧は誤りではなく空です。

照合は key で行ってください（account、lead、opportunity）。ラベルは表示用の文字列なので日本語です。

3. そのレコードを一覧する

GET /api/v1/objects/{objectId}/records?limit=10

{
  "items": [{ "id": "…", "name": "…", "revision": 3, "values": {} }],
  "nextCursor": "…",
  "total": 42
}

limit は 1 から 100 で既定は 50 です。次のページには nextCursor を after として渡し、null になったら終了します。

total は最初のページでのみ数えられます。 以降のページは total: null を返します。表示したい場合は最初のページの値を保持してください。

最小限はこれで全部です。並び順、ビュー、フィルター、関連レコードはすべて任意で、ビュー・並び順・ページネーションが拒否される 4 つのパラメータの組み合わせを含めて扱います。

最初に出る 4 つの拒否

拒否	意味	どうするか
`workspace_session_required`	Web アプリケーションのトランスポート `/api/v1/workspace/…` を呼びました。設計上ベアラートークンを拒否します	リファレンスにあるパスを使ってください
`permission_required`	トークンのスコープかメンバーの役割がそのアクションを許可していません	`capabilities` を読んでください。欲しいアクションが `actions` にありません
`feature_disabled`	そのエンドポイントのモジュールがこのワークスペースで無効です	`capabilities` を読んでください。`features` でそのモジュールが `false` です
オブジェクト一覧が空	誰も `POST /bootstrap` を実行していません	標準オブジェクトを設置するか、管理者に依頼してください

前の 3 つは同じ間違いの 3 つの形です。capabilities を先に読む代わりに、何ができるかを API に尋ねているということです。

401 は種類が違います。トークンが欠けている・不正・失効しているということで、リクエストを変えるのではなく新しいトークンを得るのが答えです。エラーが拒否の形と、再試行の価値があるものを扱います。