API Gateway

API Gateway の Route（gateway/v1alpha1 Route）。有効なバージョンの Route を通して、登録した顧客の API（api の Connection）へ要求を渡す。 gateway:routes.call が必要。呼出し元は URL を指定できず、プロジェクトに Route がなければ、別のプロジェクトにあっても同じ 404 を返す。 転送先には、決めたヘッダー（accept・content-type・idempotency-key・if-match など）と Connection の秘密値の Bearer だけを渡し、 呼出し元の資格情報と Cookie は渡さない。応答は cache-control を private にし、vary に authorization を足す（共有のキャッシュに使い回させない）。 304 はそのまま返し、ほかの 3xx は追わずに 502 にする。転送先の停止は 502（BAD_GATEWAY）、時間切れは 504（GATEWAY_TIMEOUT）。再送はしない。 顧客の API の公開（gateway/v1alpha1 PublishedApi）は Route の上にあり、Consumer の API キーで /v1/gateway/published/{api}/{path} を呼ぶ。 Consumer ごとに API キー・上限・取り消しを持ち、Consumer の API キーはこのパスのほかを呼べない

説明は公開 API の契約（OpenAPI）から生成しています。

エンドポイント

GET	/v1/gateway/invoke/{route}/{path}
POST	/v1/gateway/invoke/{route}/{path}
PUT	/v1/gateway/invoke/{route}/{path}
PATCH	/v1/gateway/invoke/{route}/{path}
DELETE	/v1/gateway/invoke/{route}/{path}
GET	/v1/gateway/published/{api}/{path}
POST	/v1/gateway/published/{api}/{path}
PUT	/v1/gateway/published/{api}/{path}
PATCH	/v1/gateway/published/{api}/{path}
DELETE	/v1/gateway/published/{api}/{path}
GET	/v1/gateway/apis
GET	/v1/gateway/tool-exposures
GET	/v1/gateway/consumers
POST	/v1/gateway/consumers/{name}/keys
DELETE	/v1/gateway/consumers/{name}/keys/{keyId}
GET	/v1/gateway/calls

invokeRouteGet

GET/v1/gateway/invoke/{route}/{path}

Route の methods に GET があるときだけ転送する

パラメーター

名前	場所	型	必須	説明
route	path	string	はい	Route の名前
path	path	string	はい	転送先で Route の path の後ろに付けるパス。/ を含めてよく、%2F に符号化しても / として扱う。符号化した \ と . 、空の区切り、. ・ .. の区切りは拒否する

応答

• 200 — object: 転送先の応答（状態コードと本文はそのまま返す）
• default — Problem: RFC 9457 Problem Details

invokeRoutePost

POST/v1/gateway/invoke/{route}/{path}

Route の methods に POST があるときだけ転送する

パラメーター

名前	場所	型	必須	説明
route	path	string	はい	Route の名前
path	path	string	はい	転送先で Route の path の後ろに付けるパス。/ を含めてよく、%2F に符号化しても / として扱う。符号化した \ と . 、空の区切り、. ・ .. の区切りは拒否する

リクエストの本文

*/*

応答

• 200 — object: 転送先の応答（状態コードと本文はそのまま返す）
• default — Problem: RFC 9457 Problem Details

invokeRoutePut

PUT/v1/gateway/invoke/{route}/{path}

Route の methods に PUT があるときだけ転送する

パラメーター

名前	場所	型	必須	説明
route	path	string	はい	Route の名前
path	path	string	はい	転送先で Route の path の後ろに付けるパス。/ を含めてよく、%2F に符号化しても / として扱う。符号化した \ と . 、空の区切り、. ・ .. の区切りは拒否する

リクエストの本文

*/*

応答

• 200 — object: 転送先の応答（状態コードと本文はそのまま返す）
• default — Problem: RFC 9457 Problem Details

invokeRoutePatch

PATCH/v1/gateway/invoke/{route}/{path}

Route の methods に PATCH があるときだけ転送する

パラメーター

名前	場所	型	必須	説明
route	path	string	はい	Route の名前
path	path	string	はい	転送先で Route の path の後ろに付けるパス。/ を含めてよく、%2F に符号化しても / として扱う。符号化した \ と . 、空の区切り、. ・ .. の区切りは拒否する

リクエストの本文

*/*

応答

• 200 — object: 転送先の応答（状態コードと本文はそのまま返す）
• default — Problem: RFC 9457 Problem Details

invokeRouteDelete

DELETE/v1/gateway/invoke/{route}/{path}

Route の methods に DELETE があるときだけ転送する

パラメーター

名前	場所	型	必須	説明
route	path	string	はい	Route の名前
path	path	string	はい	転送先で Route の path の後ろに付けるパス。/ を含めてよく、%2F に符号化しても / として扱う。符号化した \ と . 、空の区切り、. ・ .. の区切りは拒否する

応答

• 200 — object: 転送先の応答（状態コードと本文はそのまま返す）
• default — Problem: RFC 9457 Problem Details

callPublishedApiGet

GET/v1/gateway/published/{api}/{path}

Consumer の API キーで呼ぶ。Consumer に許した PublishedApi で、Route の methods に GET があるときだけ転送する。転送先には x-hane-consumer で Consumer の名前を渡す。公開していない API も、許していない API も同じ 404 を返す

パラメーター

名前	場所	型	必須	説明
api	path	string	はい	PublishedApi の名前
path	path	string	はい	転送先で Route の path の後ろに付けるパス。扱いは Route の呼出しと同じ

応答

• 200 — object: 転送先の応答（状態コードと本文はそのまま返す）
• default — Problem: RFC 9457 Problem Details

callPublishedApiPost

POST/v1/gateway/published/{api}/{path}

Consumer の API キーで呼ぶ。Consumer に許した PublishedApi で、Route の methods に POST があるときだけ転送する。転送先には x-hane-consumer で Consumer の名前を渡す。公開していない API も、許していない API も同じ 404 を返す

パラメーター

名前	場所	型	必須	説明
api	path	string	はい	PublishedApi の名前
path	path	string	はい	転送先で Route の path の後ろに付けるパス。扱いは Route の呼出しと同じ

リクエストの本文

*/*

応答

• 200 — object: 転送先の応答（状態コードと本文はそのまま返す）
• default — Problem: RFC 9457 Problem Details

callPublishedApiPut

PUT/v1/gateway/published/{api}/{path}

Consumer の API キーで呼ぶ。Consumer に許した PublishedApi で、Route の methods に PUT があるときだけ転送する。転送先には x-hane-consumer で Consumer の名前を渡す。公開していない API も、許していない API も同じ 404 を返す

パラメーター

名前	場所	型	必須	説明
api	path	string	はい	PublishedApi の名前
path	path	string	はい	転送先で Route の path の後ろに付けるパス。扱いは Route の呼出しと同じ

リクエストの本文

*/*

応答

• 200 — object: 転送先の応答（状態コードと本文はそのまま返す）
• default — Problem: RFC 9457 Problem Details

callPublishedApiPatch

PATCH/v1/gateway/published/{api}/{path}

Consumer の API キーで呼ぶ。Consumer に許した PublishedApi で、Route の methods に PATCH があるときだけ転送する。転送先には x-hane-consumer で Consumer の名前を渡す。公開していない API も、許していない API も同じ 404 を返す

パラメーター

名前	場所	型	必須	説明
api	path	string	はい	PublishedApi の名前
path	path	string	はい	転送先で Route の path の後ろに付けるパス。扱いは Route の呼出しと同じ

リクエストの本文

*/*

応答

• 200 — object: 転送先の応答（状態コードと本文はそのまま返す）
• default — Problem: RFC 9457 Problem Details

callPublishedApiDelete

DELETE/v1/gateway/published/{api}/{path}

Consumer の API キーで呼ぶ。Consumer に許した PublishedApi で、Route の methods に DELETE があるときだけ転送する。転送先には x-hane-consumer で Consumer の名前を渡す。公開していない API も、許していない API も同じ 404 を返す

パラメーター

名前	場所	型	必須	説明
api	path	string	はい	PublishedApi の名前
path	path	string	はい	転送先で Route の path の後ろに付けるパス。扱いは Route の呼出しと同じ

応答

• 200 — object: 転送先の応答（状態コードと本文はそのまま返す）
• default — Problem: RFC 9457 Problem Details

listPublishedApis

GET/v1/gateway/apis

有効な ReleaseBundle で公開している API。gateway:read が必要

応答

• 200 — object: 公開している API
• default — Problem: RFC 9457 Problem Details

listToolExposures

GET/v1/gateway/tool-exposures

有効な ReleaseBundle で Agent のツールにしている PublishedApi の操作。審査の記録は ReleaseBundle の審査に残る。gateway:read が必要

応答

• 200 — object: Agent のツールにしている操作
• default — Problem: RFC 9457 Problem Details

listConsumers

GET/v1/gateway/consumers

この環境に apply してある Consumer と API キー。gateway:read が必要

応答

• 200 — object: Consumer
• default — Problem: RFC 9457 Problem Details

createConsumerKey

POST/v1/gateway/consumers/{name}/keys

Idempotency-Key は要らない。secret を保存しないので、同じキーで送っても再送せず、別の API キーを発行する

パラメーター

名前	場所	型	必須	説明
name	path	string	はい

リクエストの本文

application/json

名前	型	必須	説明
expires_at	string		この時刻から先は入口が拒否する。省くと期限を付けない。今より後の時刻にする

応答

• 201 — object: 発行した API キー
• default — Problem: RFC 9457 Problem Details

revokeConsumerKey

DELETE/v1/gateway/consumers/{name}/keys/{keyId}

Consumer の API キーを失効する。次の要求から拒否する。gateway:consumers.manage が必要

パラメーター

名前	場所	型	必須	説明
name	path	string	はい
keyId	path	string	はい

応答

• 200 — ConsumerKey: 失効した API キー
• default — Problem: RFC 9457 Problem Details

listApiCalls

GET/v1/gateway/calls

転送した PublishedApi の呼出しと、Agent が ToolExposure で呼んだ操作の記録（新しい順、プロジェクトごとに直近の 1000 件）。本文は含まない。gateway:read が必要

パラメーター

名前	場所	型	必須	説明
consumer	query	string		この Consumer の呼出しだけを返す。Agent は agent:<名前>
limit	query	integer		返す数。省くと 100、上限は 500

応答

• 200 — object: 呼出しの記録
• default — Problem: RFC 9457 Problem Details