Skip to content

api-access.ja.mdx

Latest commit

 

History

History
132 lines (99 loc) · 6.83 KB

api-access.ja.mdx

File metadata and controls

132 lines (99 loc) · 6.83 KB
Raw
title API アクセス
description 統合のために生成される REST API、認証、API キーについて。

API アクセス

アーティファクトで宣言されたすべてのオブジェクトは、生成された REST API を通じて公開されます。同じエンドポイントが UI、統合、顧客の ETL スクリプトを支えており、別途維持すべき「統合用 API」は存在しません。

ベース URL

https://<project-domain>/api/v1

主なエンドポイント:

Path 用途
/api/v1/data/<object> 各オブジェクトに対して生成される CRUD（例: /api/v1/data/account）
/api/v1/data/<object>/{id} 単一レコードの読み取り／更新／削除
/api/v1/actions/<object>/<action> 宣言的アクションの呼び出し（POST）
/api/v1/auth/* 認証（サインイン、セッション、OAuth、OIDC）
/api/v1/meta/* 有効化されている場合のメタデータ API（オブジェクト、フィールド、ビュー）
/api/v1/keys 呼び出しユーザー向けに一度だけ表示される sys_api_key を発行（POST）
/api/v1/mcp OS_MCP_SERVER_ENABLED=true のとき、Streamable HTTP 経由の Model Context Protocol サーバー
/api/v1/health 死活／準備状態のプローブ（認証不要）

プレフィックスのデフォルトは /api/v1（API の basePath である /api と version である v1 の組み合わせ）で、ObjectOS スタック上で構成可能です。

公開範囲の制御

API の公開はゲートウェイではなく、アーティファクト内のオブジェクト単位で制御されます:

  • オブジェクトに apiEnabled: false を設定すると、REST 表面から完全に外れます （そのルートは 404 になります）。
  • apiMethods ホワイトリスト（例: ['get', 'list']）を設定すると、オブジェクトを 読み取り専用にしたり、到達可能な操作を制限したりできます。

どちらも REST レイヤーで強制適用されます。 REST API → API 表面の制限 を参照してください。

認証オプション

呼び出し元は次の 3 つの方法で認証できます:

方法 適した用途 やり方
セッション Cookie ブラウザ／UI のトラフィック /api/v1/auth/* を通じてサインインします。Cookie はプロジェクトのホスト名にスコープされます
Bearer アクセストークン モバイル、SPA、短命のサーバージョブ /api/v1/auth/sign-in/email で資格情報を交換し、Authorization: Bearer <token> を渡します
API キー サーバー間連携、ETL、長期間の統合 sys_api_key を作成し、bearer トークンとして渡します

3 つの方法はいずれも同じ AuthPlugin を通過し、SecurityPlugin が権限と レコードアクセスに対して評価する sys_user コンテキストに解決されます。

API キー

API キーはファーストクラスの sys_api_key レコードです。キーの値自体は ハッシュ化して保存され、クエリ可能なのは prefix とメタデータのみです。 そのため、漏洩したキーをデータベースから復元することはできません。

キーは次の 2 つの方法で発行できます:

  • Console — 管理者として Console → API Keys にサインインし、所有 ユーザーを選択し、必要に応じて有効期限を設定して、表示されたシークレットを 一度だけコピーします。

  • セルフサービスエンドポイント — POST /api/v1/keys は認証済みの呼び出し元 に対してキーを発行し、生のシークレットをちょうど一度だけ返します。キーは 呼び出し元自身のユーザーに固定されるため、別の ID へのなりすましには使用 できません:

    curl -X POST https://app.example.com/api/v1/keys \
  -H "Authorization: Bearer <session-or-access-token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "etl-pipeline"}'
# → { "id": "...", "name": "etl-pipeline", "prefix": "os_pk_…", "key": "os_pk_live_…" }

以降のリクエストでは、キーを bearer トークン、x-api-key ヘッダー、または Authorization: ApiKey として渡します。REST のデータ／メタデータ API はいずれも MCP と同じ検証器で認証し、キー所有者の権限とレコードレベルセキュリティの下で 実行されます:

curl https://app.example.com/api/v1/data/account \
  -H "x-api-key: os_pk_live_…"

キーを失効させるには、対応する sys_api_key レコードに対して revoke_api_key アクションを実行します（Console UI でも利用可能）。 失効は次のリクエストから即座に有効になります。

ページネーション、フィルタリング、ソート

生成されるリストエンドポイントは、標準の ObjectStack クエリパラメーターを受け付けます:

パラメーター 意味
?limit= ページサイズ（サーバー側の上限が適用されます）
?offset= または ?cursor= ページネーション
?filter= ObjectQL のフィルター構文を使用したサーバー側フィルタリング
?sort= ソート式（例: -created_at）
?fields= スパースなフィールド選択

完全なフィルター文法についてはフレームワークのドキュメントを参照してください。 ランタイムの文法が信頼できる情報源です。

レート制限

フレームワークの RateLimiter プリミティブ（または ingress / API ゲートウェイ）を使用して、IP ごと・アイデンティティごとの制限を適用します。 推奨される初期バケットは 本番環境への準備 に記載されています。

CORS

呼び出し元が異なるオリジンのブラウザで動作する場合は、ingress または ランタイムのミドルウェアで CORS を構成します。ワイルドカードオリジンと 資格情報付きリクエストを組み合わせないでください。

OpenAPI / ディスカバリー

該当する機能がイメージに含まれている場合、ランタイムは生成された REST API の OpenAPI ドキュメントを提供できます。オブジェクト名や生成されたルートは デプロイされたアーティファクトに従うため、顧客の統合では URL を手作業で 組み立てるのではなく、デプロイごとの OpenAPI ドキュメントからクライアントを 生成してください。