iii-http-endpoints

HTTP エンドポイント

類似技術：Express、Fastify、Flask

主な概念

タスクに合う場合は、以下の概念を使用します。すべての HTTP エンドポイントで、これらすべてが必要になるわけではありません。

• 各ルートは、HTTP トリガーを介してパスとメソッドにバインドされた登録済み関数です
• ハンドラーは、body、path_params、headers、method を含む ApiRequest オブジェクトを受け取ります
• ハンドラーは { status_code, body, headers } を返し、HTTP レスポンスを構成します
• RestApiModule は、ポート 3111 で登録済みのすべてのルートを提供します
• パスパラメーターにはコロン構文（例：/users/:id）を使用し、path_params に格納されます

アーキテクチャ

HTTP リクエスト
  → RestApiModule（ポート 3111）
    → registerTrigger によるルート照合（メソッド + パス）
      → registerFunction ハンドラー（ApiRequest を受け取る）
        → { status_code, body, headers } レスポンス

iii で使用するプリミティブ

プリミティブ	目的
registerFunction	ルートのハンドラーを定義する
registerTrigger({ type: 'http' })	ルートのパスとメソッドを関数にバインドする
config: { api_path: '/path', http_method: 'GET' }	トリガーのルート設定

リファレンス実装

../references/http-endpoints.js で完全な動作例をご覧ください。GET リクエストと POST リクエストを処理する、パラメーター化されたルートを備えた REST API です。

Python 版もあります：../references/http-endpoints.py

Rust 版もあります：../references/http-endpoints.rs

よくあるパターン

このパターンを使用するコードには、該当する場合、一般に以下が含まれます。

• registerWorker(url, { workerName }) — ワーカーの初期化
• registerFunction(id, handler) — ルートハンドラーの定義
• registerTrigger({ type: 'http', config: { api_path, http_method } }) — パスとメソッドのバインド
• req.body — POST/PUT リクエストの解析済みリクエストボディ
• req.path_params — 抽出されたパスパラメーター
• return { status_code: 200, body: { data }, headers: { 'Content-Type': 'application/json' } } — レスポンスの形式
• const logger = new Logger() — 各ハンドラーでの構造化ログ記録

このパターンの適用

タスクに当てはまる場合は、以下の方法で適用します。

• 異なるパスまたはメソッドで関数と HTTP トリガーを追加登録して、ルートを追加します
• リソース識別子には path_params を使用します（例：/orders/:orderId）
• 適切なステータスコードを返します（作成時は 201、見つからない場合は 404、不正な入力の場合は 400）
• 認証が必要なルートでは、req.headers を調べてトークンまたは API キーを確認します
• エンドポイントの後続処理をつなぐには、202 Accepted を返した後にキューへ登録します

パターンの境界

• タスクが iii 関数から外部 HTTP API を呼び出す内容である場合は、iii-http-invoked-functions を優先します。
• エンドポイントの背後で非同期処理が必要な場合は、バックグラウンド処理に iii-queue-processing を優先します。
• iii がルートを所有し、受信リクエストを直接処理する場合は、iii-http-endpoints を使用します。

使用する場面

• タスクの主な内容が iii エンジンにおける iii-http-endpoints である場合に、このスキルを使用します。
• リクエストでこのパターンまたは同等の実装が直接求められた場合に適用します。

境界

• 無関係なタスクに対する汎用的な代替手段として、このスキルを使用しないでください。
• より具体的な iii スキルが適している場合、このスキルを適用してはいけません。
• このスキルの例を適用する前に、環境と安全性の制約を必ず確認してください。