arch-api

目的

このスキルを使用すると、OpenClaw で REST の原則、バージョニング戦略、HATEOAS、認証パターン、OpenAPI 仕様、API ゲートウェイの設計を重視した API アーキテクチャの設計、ドキュメント作成、実装ができます。これにより、API のスケーラビリティ、安全性、標準への準拠が確保されます。

使用する場面

新しい RESTful API を設計するとき、レガシー API を最新の標準に移行するとき、後方互換性のためにバージョニングを実装するとき、またはハイパーメディア駆動のレスポンスに HATEOAS を組み込むときに、このスキルを使用します。マイクロサービス環境での適用、Swagger UI 用の OpenAPI ドキュメントの生成、保護されたエンドポイント向けの JWT などの認証パターンの評価にも利用できます。

主な機能

• REST 設計：URI 構造（例：/resources/{id}）を生成し、HTTP メソッド（GET、POST）を特定のレスポンスコード（200 OK、404 Not Found）に対応付けます。
• バージョニング：URI ベース（例：/v1/resources）またはヘッダーベース（例：Accept: application/vnd.myapi.v1+json）のバージョニングに対応します。
• HATEOAS：JSON レスポンスに自己リンクや関連リソースへのリンクを追加します。例：{"_links": {"self": "/users/1"}}。
• 認証パターン：トークンの検証やスコープ（例：read:users）を含む、JWT または OAuth2 のフローを実装します。
• OpenAPI ドキュメント：スキーマとエンドポイントを含む OpenAPI 3.0 YAML/JSON 仕様を、コードまたは設計から自動生成します。
• ゲートウェイパターン：負荷分散に Kong や AWS API Gateway などのパターンを使用する API ゲートウェイを設計します。

使用パターン

openclaw arch-api <subcommand> [flags] のコマンド構成を使用して、OpenClaw CLI からこのスキルを呼び出します。コマンドを実行する前に、必ず環境変数として認証キーを設定します：export OPENCLAW_API_KEY=your_api_key。対話的に使用する場合は、出力を他のツールに渡します。例：openclaw arch-api design --rest | jq .。複雑な入力には、次の形式の JSON 設定ファイルを使用します：{"endpoints": [{"path": "/users", "method": "GET"}]}。

REST API を設計するには、次を実行します：openclaw arch-api design --type rest --version v1 --hateoas。OpenAPI を生成するには、ソースファイルを指定します：openclaw arch-api docs --input api-spec.json --output openapi.yaml。

主なコマンド/API

• コマンド：openclaw arch-api design --rest --endpoints users/get,users/post --version v1 フラグ：HATEOAS リンクを有効にするには --hateoas、JWT 認証を追加するには --auth jwt を指定します。 コードスニペット：

  openclaw arch-api design --rest > api_design.json
  cat api_design.json | grep "uri"
  

• コマンド：openclaw arch-api generate-openapi --from-code ./src/api/controllers.py --output docs/openapi.yaml フラグ：エラーを確認するには --validate、ゲートウェイ固有のパターンを使用するには --gateway kong を指定します。 コードスニペット：

  export OPENCLAW_API_KEY=abc123
  openclaw arch-api generate-openapi --from-code .
  

• API エンドポイント：OpenClaw の内部 API を使用する場合は、本文 {"type": "rest", "version": "v1"} を指定して /v1/arch-api/design に POST します。レスポンスには、{"endpoints": [{"path": "/users", "method": "GET"}]} のような JSON が含まれます。 設定形式：入力には YAML を使用します。例：

  endpoints:
    - path: /users
      method: GET
      auth: jwt
  

• コマンド：openclaw arch-api validate --spec openapi.yaml --check hateoas フラグ：バージョンヘッダーを検証するには --check versioning を指定します。

統合に関する注意事項

コマンドを連結して、このスキルを他の OpenClaw スキルと統合します。例：openclaw chain arch-api se-deployment --input api_design.json。外部ツールを使用する場合は、出力をファイルに書き出します：openclaw arch-api design > input_for_deployment.txt。認証が必要な場合、スクリプト内では常に環境変数のパターン $OPENCLAW_API_KEY を使用します。例：bash スクリプトでは次のようにします。

#!/bin/bash
export OPENCLAW_API_KEY=your_key
openclaw arch-api design --rest

設定を共有する際は、Swagger Editor などのツールと互換性のある JSON ファイルを使用し、フィールドが OpenAPI スキーマに一致していることを確認します。

エラー処理

コマンドの終了コードを確認します：openclaw arch-api design がゼロ以外を返した場合は、stderr を解析して "Invalid endpoint format" のようなメッセージを確認します。API 呼び出しでは、HTTP エラーを処理します：status == 401 の場合は、更新した $OPENCLAW_API_KEY を使用して再試行します。スクリプトでは try-catch を使用します。

try {
  openclaw arch-api generate-openapi --input invalid.json
} catch (e) {
  if (e.includes("Validation error")) { console.log("Fix JSON schema"); }
}

よくあるエラー：入力形式が正しくない場合（例：--version フラグがない場合）は 400、$OPENCLAW_API_KEY が無効な場合は 403 です。次のようにエラーを記録します：openclaw arch-api design 2>> error.log。

具体的な使用例

1. ユーザー管理システムの REST API を設計する場合：まず、認証キーを設定します：export OPENCLAW_API_KEY=your_key。次に、次のコマンドを実行します：openclaw arch-api design --rest --endpoints users/get,users/post --version v1 --auth jwt --hateoas。これにより、{"path": "/users", "method": "GET", "_links": {"self": "/users/1"}}のようなエンドポイントを含む JSON ファイルが出力され、コードで API を構築する際に利用できます。

2. 既存のコードベースの OpenAPI ドキュメントを生成する場合：キーをエクスポートします：export OPENCLAW_API_KEY=your_key。次のコマンドを実行します：openclaw arch-api generate-openapi --from-code ./src/api --gateway aws --output api_docs.yaml。これにより、たとえば /users のパスや JWT のセキュリティスキームを含む仕様を記述した YAML ファイルが作成され、Swagger UI との統合にすぐ利用できます。

グラフの関係

• 関連先：se-deployment（ゲートウェイパターンを介して、設計した API をデプロイするため）。
• 接続先：se-architecture クラスター（協調スキルのために「api-design」などのタグを共有します）。
• リンク先：se-auth（API の認証実装の詳細を確認するため）。
• 関連先：openapi-tool（OpenAPI ドキュメント生成を拡張するため）。