web-api

web-api

目的

このスキルを使うと、OpenClaw で REST、GraphQL、tRPC を使用した Web API を設計、実装できます。OpenAPI 3.1 仕様、JWT/OAuth2 認証、レート制限、ページネーションに重点を置いています。Web アプリケーション向けに、安全でスケーラブルな API の設計図やコードスニペットを生成する際に使用します。

使用するタイミング

ユーザー認証システムの作成や、ページネーションされたデータの取得など、API エンドポイントが必要なバックエンドサービスを構築するときにこのスキルを使用します。RESTful アーキテクチャ、GraphQL クエリ、tRPC プロシージャを扱うプロジェクト、特にレート制限の適用や認証の処理が必要な場合に使用してください。

主な機能

• OpenAPI 3.1 を使用した REST API の設計：openapi-generator CLI を使って、--input spec.yaml --generator spring などのフラグを指定し、スキーマを生成します。
• GraphQL API の実装：型とリゾルバーを使ってスキーマを定義します。例：Apollo Server の設定で const typeDefs = gqlquery { users }; を使用します。
• tRPC プロシージャの処理：型付きエンドポイントを作成します。例：export const appRouter = router({ hello: publicProcedure.query(() => 'world') });。
• 認証：ミドルウェアを使って JWT または OAuth2 を適用します。トークン署名用に環境変数 $WEB_API_JWT_SECRET を設定します。
• レート制限：express-rate-limit などのライブラリを使い、{ windowMs: 15*60*1000, max: 100 } のようなオプションで制限を適用します。
• ページネーション：クエリにカーソルベースまたはオフセットベースのページネーションを実装します。例：query { users(first: 10, after: "cursor") }。

使用パターン

REST API を設計するには、openclaw run web-api --design rest --spec openapi.yaml を指定してこのスキルを実行します。GraphQL の場合は、openclaw run web-api --type graphql --schema schema.graphql を使用します。$WEB_API_OAUTH_CLIENT_ID と $WEB_API_OAUTH_CLIENT_SECRET を設定して、必ず認証を含めてください。tRPC の場合は、openclaw run web-api --type trpc --router path/to/router.ts を指定します。--rate-limit 100:15m を追加すると、レート制限を含められます。例 1：ページネーション付きのユーザーエンドポイントを作成するには、openclaw run web-api --design rest --endpoint /users --paginate offset:10 を実行し、生成されたコードを統合します。例 2：保護された GraphQL クエリには、openclaw run web-api --type graphql --auth jwt --query "query { protectedData }" を使用します。JWT 検証機能を備えたリゾルバーが出力されます。

主なコマンド／API

• CLI コマンド：openclaw run web-api --cluster web-dev --action generate --format openapi を実行すると、OpenAPI 仕様ファイルを作成できます。
• API エンドポイント：POST /api/v1/login のようなリクエストを、本文 { "username": "user", "password": "pass" }、ヘッダー Authorization: Bearer $WEB_API_JWT_TOKEN でシミュレートします。
• コードスニペット：REST サーバーのセットアップには、app.use(express.json()); app.get('/api/items', (req, res) => res.json(items)); を使用します。
• コードスニペット：GraphQL には、const server = new ApolloServer({ typeDefs, resolvers }); server.listen(); を使用します。
• 設定形式：OpenAPI には YAML を使用します。例：openapi: 3.1.0 info: title: API paths: /users: get: parameters: - name: page in: query schema: type: integer。
• tRPC の例：import { initTRPC } from '@trpc/server'; const t = initTRPC.create(); export const router = t.router({});。

統合に関する注意

コマンドを連結してこのスキルを他の OpenClaw スキルと統合できます。例：openclaw run web-api --output code.js; openclaw run database --import code.js。認証には、実行前に環境変数 $WEB_API_API_KEY が設定されていることを確認してください。API を React コンポーネント用の JSON スキーマとしてエクスポートすれば、フロントエンド関連のスキルと一緒に使用できます。依存関係は npm install express graphql @trpc/server でインストールし、生成されたコードで app.use(rateLimit({ max: 100 })); を使ってレート制限を設定します。OpenAPI 仕様をインポートし、Postman などのツールで統合をテストしてください。

エラー処理

エラーが発生した場合は、例外を捕捉して無効な JWT などの一般的な問題を確認します。try { jwt.verify(token, process.env.WEB_API_JWT_SECRET); } catch (err) { res.status(401).send('Invalid token'); }。レート制限に達した場合は、再試行までの時間を示すヘッダーを付けて 429 レスポンスを返します。OpenClaw のエラーログを使用します。openclaw log error --message "API rate limit exceeded" --skill web-api。レスポンスから API エラーを解析します。たとえば、ステータスが 400 の場合は、{ error: 'Bad request' } のようにエラー本文を抽出します。API 呼び出しは必ず try-catch ブロックで囲み、機密データの漏えいを防ぐために環境変数を使用します。

グラフの関係

• 関連：UI と API の統合に関する「frontend」スキル。
• 接続：API でのデータソースのクエリに関する「database」スキル。
• 連携：「auth」スキルで共有する JWT／OAuth2 の実装。
• 関連：「deployment」スキルでの API サーバーのホスティング。