APIゲートウェイとルーティング

1）アーキテクチャにおけるAPIゲートウェイの役割

• 受信トラフィックを受け付ける（HTTP/HTTP2/HTTP3、 WebSocket、 gRPC）
• ルール（host/path/headers/method/query/geo/weight/health）に従ったルート；
• エンドツーエンドのポリシーを適用します：認証/承認、レート制限、WAF、 CORS、キャッシュ；
• 変換を実行します（ヘッダー/ボディ、gRPC↔JSON、 GraphQLステッチの正規化）。
• 安定性を提供します（タイムアウト、リトライ、サーキットブレーカー、アウトリア検出）。
• オブザビリティと請求（ログ、メトリック、トレース、クォータ）を提供します。
• 内部トポロジ（サービスメッシュ、プライベートサービス）を分離します。

ペアでよく使用される：Edge/API-Gateway+Ingress/Mesh （Envoy/Istio/Linkerd）-最初は外交政策、2番目-東西を決定します。

2）典型的なトポロジー

単一のグローバルゲートウェイ（CDN/エッジPOP→L7ゲートウェイ→サービス）-シンプルで集中型のポリシー。
地域ゲートウェイ（地域ごと）+スマートジオルーティング/レイテンシルーティング。
マルチテナント：専用ルート/サブドメイン/キー、クォータおよびテナントあたりの制限。
ハイブリッド：オンプレミス+クラウド、プライベートリンク/ピアリング、APIゲートウェイの背後にあるプライベートバックエンド。

3） L7ルーティングルール

• ホスト/パス：'api。例を示します。com'→'/v1/orders/'。
• ヘッダー：'X-Client'、 'X-Region'、 'User-Agent'、 'Accept'。
• メソッド/Content-Type： JSON/Proto/GraphQLを区別します。
• Query/Fragment： careful-キャッシュ/バリアントに影響を与えます。
• Geo/Latency：最寄りのPOP/region、劣化しているフェイルオーバー。
• 重み付け/カナリア：トラフィック分布90/10、50/50、クッキーによる粘着性。
• セッションアフィニティ：キー/トークンに基づくハッシュベース（スケーリング時に注意）。

yaml nginx. ingress. kubernetes. io/canary: "true"
nginx. ingress. kubernetes. io/canary-weight: "10" # 10% traffic to new backend

yaml match: { prefix: "/orders", headers: [{name: "X-Experiment", exact_match: "new"}] }
route: { cluster: orders-v2 }

4）プロトコルと互換性

REST/JSON-デフォルトで、クライアント検証/生成のためのOpenAPIを説明します。
gRPC-HTTP/2上のバイナリプロト；外部クライアントの場合は、gRPC-JSONトランスコーディングを使用します。
GraphQL-サービスを集約します。周囲では、クエリの複雑さ/深さを監視します。
WebSocket/SSE-双方向/プッシュ；粘着性とタイムアウトを考慮してください。
HTTP/2/3 （QUIC）-多重化/高速開始；WAF/プロキシの互換性を確認します。

5）保証： 認証および承認

5.1トランスポート

TLS 1。周囲、HSTS、 OCSPのステープル、PFSの2+。
B2B/internal APIとマシン間のmTLS。
IP allowlist/denylist、 geo-constraints。

5.2アプリケーション層

OAuth2/OIDC： JWTベアラートークン、署名/有効期限/オーディエンス検証。
NMAS/signatures： date+canonized line+signature （AWS-like）-置換、反復（nonce/time window）に対する保護。
APIキー：識別子としてのみ；rights-RBAC/ABAC/scopesを介して。
CORS：明示的なallow-origin、プリフライトキャッシュ。
WAF：署名（OWASP API Top 10）、異常、ボット保護、再帰JSONフィールド。
DDoS/乱用：接続制限、トークンバケット/リーキーバケット、バースト+平均速度、ダイナミックバン。

yaml plugins:
- name: oidc config: { issuer: "...", client_id: "...", client_secret: "...", scopes: ["orders. read"] }
- name: rate-limiting config: { minute: 600, policy: local }

6）検証、変換、互換性

スキーム：OpenAPI/JSON-Schema/Protobufによるbody/headers/parametersの検証。
変換：フィールド正規化、PIIマスキング、相関ヘッダの追加（'traceparent'、 'x-request-id'）。
バージョン管理：'Header： X-API-Version'、 prefixes '/v1'、resource-versioning；デプロイメントポリシー；日没。
後方コンパット：アドフィールドのみ；新しいバージョンなしで変更を「破る」ことは避けてください。
Idempotency： 'Idempotency-Key' POST；ゲートウェイはRedisにTTLでキーを格納します。

7）回復力： 接続ポリシー

タイムアウト：接続/読み取り/書き込み；妥当なデフォルト（例：1s/5s/5s）。
再試行：安全で偶像性のためにのみ；ジッタ、指数関数的なバックオフ、最大の試み。
サーキットブレーカ：エラー/レイテンシで開きます。サンプルのために半開き。
アウトリエ検出-プールから悪いインスタンスを削除します。
隔壁/競争：ルートごとの同時リクエストの制限。
フェイルオーバー：アクティブ/パッシブ、ゾーンの劣化。
シャドウトラフィック：比較のためにV2「灰色」がV1と平行に実行されます（応答に影響はありません）。

yaml circuit_breakers:
thresholds:
- priority: DEFAULT max_connections: 1024 max_pending_requests: 2048 max_retries: 3

8）キャッシュとパフォーマンス

HTTP： 'Cache-Control'、 'ETag/If-None-Match'、 'Vary'、 'stale-while-revalidate'。
エッジキャッシュ/POP：静的およびキャッシュされたAPI （idempotent GET）用のCDN。
圧縮：'gzip/br'（圧縮済みではありません）。
Request collapsing （「coalescing」）：同一の並列要求を組み合わせます。
レスポンスシェーピング：フィールド/フィルタ、カーソルベース、サイズ制限。

9） Observabilityおよび操作

'l7_req_total {route、 method、 code}'、 'latency_ms {p50、 p95、 p99}'、 'upstream_errors'、 'retry_count'、 'cb_state'、 '429_rate'、 'quota_usage {tenant}'。
ログ：構造、'trace_id/span_id'、 'user_id/tenant_id'、 'client_ip'。
トレース：W3Cトレース・コンテキスト（'traceparent'、 'tracestate'）、上流に伝播する。
監査：誰が何を引き起こしたか、どのような権利で；機密性の高いAPI用の不変ストア。
SLO/SLA：ターゲットp99、エラー予算；ルートレベルはグローバルよりも優れています。

10）容量計画管理

min/hour/dayのテナント/キー/顧客プールごとのクォータ。
バースト+持続限界；滑らかになることのための漏出バケツ。
公平性：オーバーロード時-「最初に遭遇した」の代わりにフェアキュー。
優先順位：優先度と専用プールを備えたシステム/クリティカルルート。

11）変更管理とリリース

カナリア/ブルーグリーン：重量ルーティング；SLOの自動アドバンス（エラー/レイテンシ）。
フィーチャーゲート/バックエンドフラグ：ヘッダー/トークンで有効にします。
シャドーイング/差分バリデータ：ボディ/ステータスの比較、デルタ公差。
ステージング：割り当てられたドメイン/パス（'ステージング。API……'）、個々のキーとクォータ。

12）構成例

12.1 NGINX-基本制限とキャッシュゲートウェイ

nginx map $http_x_request_id $reqid { default $request_id; }

limit_req_zone $binary_remote_addr zone=perip:10m rate=10r/s;

server {
listen 443 ssl http2;
server_name api. example. com;

security add_header Strict-Transport-Security "max-age = 31536000" always;

location /v1/ {
limit_req zone=perip burst=30 nodelay;
proxy_set_header X-Request-ID $reqid;
proxy_set_header Authorization $http_authorization;
proxy_connect_timeout 1s;
proxy_read_timeout 5s;

proxy_cache api_cache;
proxy_cache_valid 200 10s;
proxy_cache_use_stale error timeout updating;
proxy_pass http://orders-v1;
}
}

12.2 Envoy-バランスとリトレイルーティング

yaml routes:
- match: { prefix: "/orders" }
route:
weighted_clusters:
clusters:
- name: orders-v1 weight: 90
- name: orders-v2 weight: 10 retry_policy:
retry_on: "5xx,reset,connect-failure"
num_retries: 2 per_try_timeout: 2s

12.3 Traefik-ミドルウェアとヘッダー

yaml http:
middlewares:
secHeaders:
headers:
stsSeconds: 31536000 contentTypeNosniff: true routers:
api:
rule: "Host(`api. example. com`) && PathPrefix(`/v1`)"
service: svc-orders middlewares: ["secHeaders"]

13）アンチパターン

「良い隣人」は「騒々しい」ために苦しんでいます。
idempotency→duplicateエフェクト（payment、 creating entities）を使用せずに再送信します。
'timeout'/'max body size'→hangs/exhausts workersを無視します。
ゲートウェイでのエッジポリシーとビジネスロジックの混在（周囲の重み付け）。
スキームの検証の欠如→クライアントの脆弱性と「破損」リリース。
auth/limits/idle-timeを除くNaked WebSocket。
回転のない見出しの秘密；内部B2BsにmTLSはありません。

14）テストプレイブック（ゲーム日）

リクエストの嵐：リミッター/クォータのチェック、429-behavior、劣化。
1つのクラスタの損失：フェイルオーバー/重量再配布；SLOカナリア。
重み付けされた答え：最大ボディ/タイムアウト；関節の切断。
注射/異常：WAF規則、再帰的JSON阻害、大きなGraphQL深度。
トレースは'traceparent'伝播とサンプリングをチェックできませんでした。
秘密：キーの回転/JWKS、トークンの有効期限、クロックスキューの許容。

15）実装チェックリスト

• 定義されたドメイン/パス/バージョン、OpenAPI/Protoが公開されました。
• TLS/mTLS、 HSTS、シークレット管理および回転が設定されています。
• 認証（OIDC/HMAC）、 RBAC/スコープ、 CORS有効。
• テナントごとの制限/クォータ、公正なキュー、429-UX。
• 重量/ヘッダルーティング、カナリアプラン、ロールバック。
• timeout/retry/circuit-breaker/outlierポリシー。
• スキーム検証、変換、PIIマスキング。
• ETag、 coalescing、 gzip/br。
• オブザビリティ：メトリック、ログ、トラック、ダッシュボード、アラート。
• Runbooks：インシデント、キー回転、ブロックリスト、ブラックフライデー。

16） FAQ

Q： APIゲートウェイはサービスメッシュとどのように異なりますか？
A：ゲートウェイ-南北（外周、エンドツーエンドのポリシー）。メッシュ-東西（メッシュ内接続/MTLS/レトライ）。よく一緒に使用されます。

Q：ゲートウェイやサービスにauthを実装する場所は？
A：両方のレベル：ゲートウェイ-粗粒（認証、基本的な権利/クォータ）、サービス-細粒（ドメインロール/属性）。

Q： gRPC-JSONトランスコーディングはいつ必要ですか？
A：内部gRPCと外部がREST/JSONとシンプルなクライアント/ブラウザを必要とする場合。

Q：バージョン戦略を選択するには？
A：公開APIの場合-パス'/vN'+剥奪ヘッダと長いオーバーラップ。内部-capability-flags/compatibilityスキームの場合。

17）合計

APIゲートウェイは単なるプロキシではなく、ポリシーとレジリエンスの中心です。適切なルーティング、セキュリティ、制限、検証、およびオブザビリティにより、リリースの予測可能性とスピードが得られます。エッジゲートウェイとサービスメッシュを組み合わせ、カナリアとクォータを自動化し、テストの失敗-周囲はボトルネックではなく、アクセラレータになります。