コンポーネントレジストリサマリの取得

メソッド

この API は REST の方法論に従います。

HTTP メソッド

GET: プロジェクトのコンポーネントレジストリのサマリを読み取ります — コンポーネント sweep が実際に登録した内容です。

これはプラグインの 「What's in the registry」 パネルであり、コンポーネントアップロードや resync が機能したかを確認する手段です。

命名規則

レスポンスは内部の wf2des-api データプレーンから 逐語でプロキシ されるため、フィールドは snake_case です。

リクエストとレスポンス

ヘッダー

リクエストヘッダー

Authorization
Accept
Accept-language

レスポンスヘッダー

Content-Type

レジストリサマリの取得

URI

GET /api/v1/organizations/{organization_id}/projects/{project_id}/wf2des/registry

パスパラメータ

名前	型	必須	説明
organization_id	integer	必須	組織 ID
project_id	integer	必須	プロジェクト ID

レスポンス

レスポンスは JSON です（HTTP ステータス: 200 OK）。

{
  "total": 279,
  "published": 173,
  "local": 106,
  "names": ["Button", "Card", "Checkbox", "Divider", "Footer-SP"]
}

レスポンスフィールド

名前	型	説明
total	integer	このプロジェクトのレジストリが保持するコンポーネント数。
published	integer	`kind: "published"` の件数 — publish key を持ち、プラグインがインスタンス化できるコンポーネント。
local	integer	`total - published`。REST sweep が作った publish key を持たない双子を含むローカルコンポーネント。
names	string[]	アルファベット順のコンポーネント名のサンプル（上限 50 件、全件ではない）。

published と local の読み方

有用なシグナルは total ではなく published と local の比です。publish key を持たないコンポーネントは プラグインでは一切マテリアライズできません。したがって local が大きいということは、レジストリが実用的な充実度より多く見えているということです。

この差はコンポーネントアップロードの直後には想定内です — REST sweep はデザインシステムライブラリの内部を読めないため、publish key を持たないローカルの双子を作ります。これを変換するのがコンポーネントキャプチャの送信です。キャプチャは component_key について正規であるため、total が変わらないまま published が増え local が減ります。

ボード単位の内訳が無い理由

design_component 文書はコンポーネント自身のノードを記録するもので、どのボードから sweep されたかは記録しません。そのためボード単位の集計はここからは導出できません。プロジェクト全体の総数、published/local の内訳、上限付きの名前サンプルが、レジストリが実際に答えられる内容です。

認証

認証は Amazon Cognito が発行する JSON Web Token（JWT）で行われます。加えて、呼び出し元はプロジェクトへのアクセス権を保持している必要があります。

エラーハンドリング

説明	ステータスコード	ステータス名
認証情報の欠落	401	Unauthorized
権限不足	403	Forbidden
プロジェクトまたは組織が見つからない	404	Not Found
上流の読み取り失敗（wf2des-api）	500	Internal Server Error

レジストリが空の場合は 404 ではなく、total: 0 とともに 200 を返します。

処理フロー

パスパラメータから組織 ID とプロジェクト ID を取得する。
ユーザーがプロジェクトへのアクセス権を持つことを検証する。
組織とプロジェクトにスコープした上で、内部 wf2des-api データプレーンへ読み取りをプロキシする（X-AI-Service-Token）。
データプレーンはプロジェクトの design_component 文書を数え、published の部分集合を数え、名前を最大 50 件アルファベット順に読む。
サマリを逐語で返す。