DEV Community: Akira

ETagとCache-ControlによるAPIキャッシング：条件付きリクエストでペイロードを削減する方法

Akira — Mon, 31 Aug 2026 11:32:05 +0000

おそらく、あなたのAPIは毎日何千回も同じJSONを返しています。クライアントがGET /v1/products/42で18KBのデータを取得し、5分後に再度要求しても、何も変更されていないのに同じ18KBを受け取ります。そのたびに帯域幅、シリアライゼーション、データベース読み取りのコストが発生します。

今すぐApidogを試す

HTTPには、この無駄を解消する仕組みがすでにあります。Cache-Controlはレスポンスの鮮度を指定し、ETagは内容が変更されたかを判定するフィンガープリントを提供します。両者を組み合わせると、再検証が必要なリクエストをボディなしの304 Not Modifiedに変えられます。さらに、書き込み時の更新損失も防止できます。

同じ考え方はクライアント側にも適用できます。ReactでのAPIレスポンスのキャッシュを読んだことがあるなら、この記事はそのサーバーサイド版です。

このガイドでは、HTTPキャッシュの3つの層、304のラウンドトリップ、no-cacheとno-storeの違い、Expressでの実装、そしてApidogでの検証方法を説明します。

HTTPキャッシュの3つの層

APIのHTTPキャッシュは、次の3つの判断に分けて考えると整理しやすくなります。

レイヤー1: 鮮度

クライアントがオリジンへ問い合わせずにレスポンスを再利用できる期間です。

Cache-Control: max-age=60

60秒間はネットワーク通信なしでキャッシュを返せます。最も安価なキャッシュヒットですが、TTLが切れるまで変更を検出できないというトレードオフがあります。

レイヤー2: 検証

レスポンスが古くなっても、クライアントはボディ全体を再ダウンロードする必要がありません。保存していたフィンガープリントを送って、変更の有無だけを確認できます。

If-None-Match + ETag: 正確な検証
If-Modified-Since + Last-Modified: 1秒単位のタイムスタンプによる古い方式

変更がなければ、サーバーはボディなしの304 Not Modifiedを返します。

レイヤー3: 無効化

データが変更されたとき、古いコピーをどう失効させるかという問題です。

プライベートキャッシュ: max-ageで自然に失効
共有キャッシュ/CDN: 明示的なパージ、短いTTL、stale-while-revalidateなどが必要

鮮度は最も大きな節約を生み、検証は鮮度で取りこぼすケースを補い、無効化は両方を正しく保ちます。多くのAPIでは、この3つすべてが必要です。

304 Not Modifiedのラウンドトリップ

製品エンドポイントの流れを見てみましょう。

1. 初回リクエスト

クライアントにはキャッシュがありません。

GET /v1/products/42 HTTP/1.1
Host: api.example.com

2. 初回レスポンス

サーバーはボディとキャッシュメタデータを返します。

HTTP/1.1 200 OK
Cache-Control: private, max-age=60
ETag: "33a64df551425fcc55e4d42a148795d9f2"
Content-Type: application/json
Content-Length: 18432

クライアントはボディとETagを保存します。次の60秒間はサーバーへ問い合わせません。

3. 60秒後の再リクエスト

キャッシュが古くなったため、クライアントはETagを送って再検証します。

GET /v1/products/42 HTTP/1.1
Host: api.example.com
If-None-Match: "33a64df551425fcc55e4d42a148795d9f2"

4. リソースに変更がない場合

サーバーが現在のETagと受信した値を比較し、一致すれば次を返します。

HTTP/1.1 304 Not Modified
Cache-Control: private, max-age=60
ETag: "33a64df551425fcc55e4d42a148795d9f2"

ボディはありません。18KBの代わりに数百バイト程度のヘッダーだけが転送され、クライアントは保存済みのボディをさらに60秒間新鮮なものとして扱います。

製品が変更されていれば、新しいボディとETagを含む通常の200 OKを返します。304 Not Modifiedの解説でも詳しく説明していますが、304はエラーではなく、キャッシュ制御のためのレスポンスです。

条件付きGETでも、ラウンドトリップ、認証、現在のETagを計算するコストは残ります。一方で、ペイロード転送とクライアント側の再解析を省けます。モバイルクライアントがポーリングする大規模なリストAPIでは、エグレスを日常的に60〜90%削減できる場合があります。

APIで重要なCache-Controlディレクティブ

Cache-Controlには多数のディレクティブがあります。JSON APIでは、特に次の5つを理解しておきましょう。

`no-store`と`no-cache`

最も頻繁に起きるキャッシュ設定ミスです。

no-store: レスポンスをどのキャッシュにも保存しない
no-cache: 保存は許可するが、再利用前に必ずオリジンで再検証する

トークン、銀行データ、永続化すべきでないPIIなど、本当に機密性の高いデータにはno-storeを使います。

一方、no-cacheは名前に反してキャッシュを禁止しません。ETagと組み合わせれば、古いデータを表示せず、変更がない場合は304でペイロードを節約できます。「安全のため」とすべてにno-storeを指定すると、条件付きリクエストまで無効になり、毎回フルペイロードを転送することになります。

`private`

エンドユーザーのクライアントだけがキャッシュでき、共有キャッシュやCDNには保存しないことを示します。

ユーザーごとに異なるレスポンス、特に認証済みAPIにはprivateを含めてください。設定がないと、誤設定されたプロキシがあるユーザーのアカウントデータを別のユーザーへ返す可能性があります。

`max-age`

レスポンスを新鮮とみなす期間を秒単位で指定します。APIでは30〜300秒程度の短い値から始めるのが実用的です。目的は1日分の通信をなくすことではなく、バーストやポーリングループを吸収することです。

`stale-while-revalidate`

古いコピーを一時的に返しながら、バックグラウンドで更新するための実用的な中間策です。

Cache-Control: max-age=60, stale-while-revalidate=300

この設定では、キャッシュは最大5分間まで古いコピーを返し、その間に更新を開始できます。ユーザーはすぐにレスポンスを受け取り、オリジンはその後更新されます。Cloudflare、FastlyなどのCDNやブラウザがサポートしています。

認証済みの読み取りエンドポイントでは、次のような設定が適切なデフォルトになります。

Cache-Control: private, max-age=60, stale-while-revalidate=120
ETag: "9f8b2c41aa73e0d5"

詳細は、HTTPキャッシュの標準であるRFC 9111を参照してください。RFC 9111はRFC 7234を置き換えています。

Strong ETagとWeak ETag

ETagには、W/プレフィックスの有無で区別される2種類があります。

Strong ETag

ETag: "33a64df551425fcc"

バイト単位で完全に一致することを保証します。同じstrong ETagを持つレスポンスは同一です。そのため、バイトレンジリクエストに安全で、If-Matchによる並行性制御にも必要です。

Weak ETag

ETag: W/"33a64df551425fcc"

意味的な同等性だけを保証します。フィールド順やタイムスタンプが異なっていても、意味が同じなら同じキャッシュコピーを利用できます。

注意点は圧縮ミドルウェアです。Nginxや一部のフレームワークは、レスポンスをgzip圧縮するとstrong ETagをweak ETagに書き換えることがあります。圧縮後のバイト列は元のボディと異なるためです。

プロキシ越しの並行性チェックが不可解に失敗する場合は、アプリケーションサーバーが生成していなかったW/プレフィックスが付いていないか確認してください。

デフォルトでは、非圧縮ボディから計算したstrong ETagを使います。異なる表現でも意図的に意味的同等性として扱いたい場合だけ、weak ETagを使ってください。

ETagの生成: ボディハッシュとバージョンカラム

主な戦略は2つです。選択は、どの処理コストを削減したいかで決まります。

レスポンスボディのハッシュ

レスポンスをシリアライズし、MD5やSHA-1でハッシュ化して引用符で囲みます。これはセキュリティ境界ではなくフィンガープリントなので、MD5やSHA-1で十分です。

ETag: "<response-hash>"

スキーマ変更が不要で、内容に対して正確です。ただし304を返す場合でも、完全なレスポンスを構築してハッシュ化する必要があります。帯域幅は節約できますが、CPUやデータベース負荷は減りません。

バージョンカラムまたは`updated_at`

安価に取得できる値からETagを生成します。

ETag: "42-v17"

条件付きリクエストを、完全なシリアライゼーションではなくインデックス付きルックアップ1回で処理できます。

ただし、結合先のテーブルを含め、レスポンスに影響するすべての変更でバージョンを更新しなければなりません。更新漏れがあると、古い304を返すという発見しにくい重大なバグになります。

まずはボディハッシュから始めるのが安全です。プロファイリングでシリアライズコストが問題になったホットエンドポイントだけ、バージョンベースのETagへ移行しましょう。

楽観的並行性制御: `If-Match`と`412`

読み取りの帯域幅を節約する同じフィンガープリントで、書き込み時の更新損失も防げます。

例えば、2人の管理者が同時に製品42を読み込んだとします。管理者Aが価格を変更して保存した後、管理者Bが30秒後に誤字を修正して保存すると、Aの価格変更をBの古いデータで上書きしてしまう可能性があります。エラーが発生しないまま、データだけが静かに壊れます。

解決策は、クライアントが最後に見たバージョンを使って更新を条件付きにすることです。

PUT /v1/products/42 HTTP/1.1
If-Match: "33a64df551425fcc55e4d42a148795d9f2"
Content-Type: application/json

サーバーはIf-Matchを現在のETagと比較します。

一致: 更新を適用し、新しいETagとともに200 OKを返す
不一致: 更新を拒否し、412 Precondition Failedを返す

不一致の場合、クライアントは最新データを再取得し、変更を再適用してから再試行します。412 Precondition Failedの詳細も参照してください。

さらに厳格にするなら、If-MatchなしのPUTに対して428 Precondition Requiredを返し、条件付き更新を必須にします。

CDNとプロキシの動作

共有キャッシュはオリジンとクライアントの間で、同じヘッダーを独自のルールに従って処理します。

privateはレスポンスをCDNキャッシュから除外します。s-maxage=600を使うと、ブラウザのmax-ageとは別にCDNのTTLを設定できます。
多くのCDNは条件付きリクエストでオリジンを再検証します。オリジンがIf-None-Matchに304を返すと、CDNはボディを再取得せず、保存済みコピーのメタデータを更新できます。
Varyが正しく設定されているか確認してください。1つのURLでJSONとCSVを返す場合はVary: Acceptが必要です。設定しないと、共有キャッシュがCSVをJSONクライアントへ返す可能性があります。
圧縮によってプロキシがETagをweak ETagへ変換することがあります。

Expressの例: ETagの返却と`If-None-Match`の処理

Expressはデフォルトでweak ETagを設定します。手動で処理すれば、strong ETagと412を使った書き込み制御を実装できます。

import crypto from "node:crypto";
import express from "express";

const app = express();
app.use(express.json());

function etagFor(payload) {
  const hash = crypto.createHash("sha1")
    .update(JSON.stringify(payload))
    .digest("hex");
  return `"${hash}"`;
}

app.get("/v1/products/:id", async (req, res) => {
  const product = await db.products.find(req.params.id);
  const etag = etagFor(product);

  res.set("Cache-Control", "private, max-age=60, stale-while-revalidate=120");
  res.set("ETag", etag);

  if (req.get("If-None-Match") === etag) {
    return res.status(304).end();   // fingerprint matches: no body
  }
  res.json(product);
});

app.put("/v1/products/:id", async (req, res) => {
  const product = await db.products.find(req.params.id);
  const currentEtag = etagFor(product);
  const ifMatch = req.get("If-Match");

  if (!ifMatch) {
    return res.status(428).json({ error: "If-Match header required" });
  }
  if (ifMatch !== currentEtag) {
    return res.status(412).json({ error: "Resource changed since you fetched it" });
  }

  const updated = await db.products.update(req.params.id, req.body);
  res.set("ETag", etagFor(updated));
  res.json(updated);
});

304の分岐でもCache-ControlとETagを返している点に注目してください。RFC 9111では、304は保存済みレスポンスのメタデータを更新するために使われます。クライアントがコピーを新鮮に保つために必要なヘッダーを再送信してください。

Apidogでキャッシュ動作を検証する

ミドルウェアやプロキシが間に入ると、コードが正しくてもキャッシュ動作が変わることがあります。コードではなく、実際のHTTPレベルで検証しましょう。

Apidogなら、手動確認は1分程度で完了します。

GET /v1/products/42を送信し、レスポンスヘッダーでETagとCache-Controlを確認します。ETagが引用符で囲まれていることも確認し、値をコピーします。
同じリクエストにIf-None-MatchヘッダーとしてETagを追加し、再送信します。ボディなしの304が返るはずです。200が返る場合、サーバーがフィンガープリントを比較していません。
レコードを変更して再送信し、新しいETag付きの200が返ることを確認します。

デプロイ後も維持できるよう、同じ流れをテストシナリオに組み込みます。

1つ目のリクエストでレスポンスヘッダーからETagを変数へ抽出
2つ目のリクエストで、その値をIf-None-Matchとして送信
ステータスが304で、ボディが空であることをアサート
3つ目のリクエストで古いIf-Match（例: "deadbeefcafe1234"）を含むPUTを送信し、412をアサート

APIアサーションでは、ステータスコードとヘッダーのアサーション構文を解説しています。

このシナリオをCIで実行すれば、ETagを削除するミドルウェアのアップグレードを、帯域幅の請求書ではなく失敗したパイプラインとして検出できます。Apidogを無料でダウンロードして、自分のエンドポイントでシナリオを作成してみてください。

よくある質問

`no-cache`と`no-store`の違いは何ですか？

no-storeはキャッシュを完全に禁止します。ディスクやメモリに保存されないため、すべてのリクエストで完全なレスポンスをダウンロードします。

no-cacheは保存を許可しますが、再利用前に毎回再検証を要求します。ETagと組み合わせれば、変更がない場合は304を返し、ペイロードを節約できます。

no-storeは機密データに限定してください。すべてのレスポンスに適用するのは、APIチームが犯しうる最も高価なCache-Controlのミスの1つです。

ETagはPOSTで機能しますか？

ほとんどの場合、機能しません。ETagはURL上のリソース状態を表すもので、POSTは通常、既存リソースを安定して読み取る操作ではなく、新しいリソースを作成する操作だからです。キャッシュは一般にPOSTレスポンスを保存しません。

書き込みで重要なのは、PUT、PATCH、DELETEにおけるIf-Matchです。これによりETagで更新損失を防げます。POSTレスポンスをキャッシュしたくなった場合、その操作はGETであるべきかもしれません。

304レスポンスはAPIを高速化しますか？

転送量は減りますが、必ずしもオリジン処理が高速化するわけではありません。サーバーはリクエストを受け取り、認証を行い、現在のETagを計算する必要があります。CPU節約効果は、フィンガープリントをどれだけ安価に導出できるかに依存します。

主なメリットは、帯域幅、モバイルバッテリー、低速ネットワークでのレンダリング時間です。導入前後で測定してください。APIパフォーマンステストガイドでは、レイテンシとスループットのベンチマーク方法を解説しています。

ETagとLast-Modifiedのどちらを使うべきですか？

可能であれば両方送信してください。ETagの方が正確で、1秒未満の変更やコンテンツレベルの差異も検出できます。両方が送信された場合、If-None-MatchはIf-Modified-Sinceより優先されます。

Last-Modifiedは、古いクライアントへのフォールバックや、キャッシュが鮮度を推定するためのヒューリスティックとして有用です。1つだけ選ぶなら、ETagを使ってください。

REST API命名規則：実践スタイルガイド

Akira — Mon, 31 Aug 2026 11:30:21 +0000

REST APIの命名規則：一貫性のあるエンドポイントを設計する10のルール

2年以上前のコードベースを開けば、そこに傷跡を見つけるでしょう。/getUser、/user_list、[REDACTED PATH]IDフィールドがorder_idの隣に存在している、といった具合です。どれも単独では何かを壊しません。しかし、積み重なるとチーム全体の作業を遅らせます。

今すぐApidogを試す

命名は、API設計で最も安価に決められる一方、後から変更するには最も高価な要素です。クライアントが/getOrdersに依存すれば、その名前を何年もサポートすることになります。

この記事では、REST APIの命名に関する具体的なルールを、推奨例と非推奨例とともに紹介します。開発者向けREST APIガイドラインと同じ考え方に基づきつつ、チームで議論になりやすい「物事をどう呼ぶか」に焦点を当てます。

コードレビューだけに頼らず、ツールでルールを強制したい場合は、Apidogで共有スキーマに対してエンドポイントを視覚的に定義できます。

1. コレクションには複数形の名詞を使用する

URLは操作ではなく、リソースを表します。コレクションは複数のリソースの集合なので、複数形の名詞で命名します。

推奨：

GET /v1/products
GET /v1/products/89
GET /v1/orders

非推奨：

GET /v1/getProducts
GET /v1/product
GET /v1/productList

複数形なら、次の2つを自然に表現できます。

/products：製品のコレクション
/products/89：コレクション内の製品89

単数形を使うと、1件のリソースには/product/89、複数のリソースには/productという不自然な構造になりがちです。Microsoft REST APIガイドラインもこの理由から複数形を採用しており、Stripe、GitHub、Shopifyなど多くの公開APIも同じ方式です。

ただし、シングルトンリソースは例外です。ユーザーがカートを1つだけ持つなら、`[REDACTED PATH]数が1のリソースには単数形を使用します。

2. パスから動詞を除外する

HTTPメソッドが動詞の役割を担います。パスにも動詞を含めると情報が重複し、リソースモデルが不明確になります。

推奨：

http GET /v1/orders/42 (読み取り) DELETE /v1/orders/42 (削除) PATCH /v1/orders/42 (更新)

非推奨：

http GET /v1/fetchOrder/42 POST /v1/deleteOrder/42 POST /v1/updateOrderStatus

動詞ベースのパスは、APIの表面積も増やします。1つのリソースに4つのメソッドがあれば、それぞれを個別にドキュメント化、テスト、キャッシュする必要があります。

キャッシュの無効化も複雑になります。CDNはGET /v1/orders/42をキャッシュし、DELETE /v1/orders/42で無効化できます。どちらも同じURLを指すためです。一方、/fetchOrder/42と/deleteOrder/42を同じリソースとして関連付けるのは困難です。

3. URLパスにはケバブケースを使用する

複数の単語で構成されるパスセグメントには、ハイフンを使います。

推奨：

http /v1/gift-cards /v1/shipping-addresses

非推奨：

http /v1/giftCards /v1/gift_cards /v1/GiftCards

ケバブケースには、主に3つの利点があります。

Googleはハイフンを単語の区切りとして扱うため、公開APIドキュメントの検索性を高められる
URLに下線が引かれた場合でも、アンダースコアのように区切りが見えなくならない
キャメルケースによる大文字・小文字の違いに起因するバグを避けられる

多くのサーバーでは/giftCardsと/giftcardsは異なるURLです。入力ミスによる問題も起こり得ます。Zalando RESTful APIガイドラインでも、ケバブケースはMUSTルールです。

4. JSONの命名規則を一つ選び、文書化する

JSONフィールド名は、キャメルケースでもスネークケースでも構いません。問題なのは、両者を混在させることです。

推奨：どちらか一方に統一する

json { "orderId": 42, "createdAt": "2026-08-30T09:15:00Z", "totalAmount": 4999 }

json { "order_id": 42, "created_at": "2026-08-30T09:15:00Z", "total_amount": 4999 }

非推奨：

json { "orderId": 42, "created_at": "2026-08-30T09:15:00Z", "TotalAmount": 4999 }

キャメルケースはJavaScriptやJavaクライアントにマッピングしやすく、スネークケースは読みやすく、Ruby、Python、SQLのカラム名と対応させやすいという特徴があります。Stripeはスネークケースを全面的に採用しています。

APIの主要な利用者に合わせて一方を選び、スタイルガイドに明記しましょう。エンドポイントごとに異なる命名規則が使われるのは、好みの問題ではなくガバナンスの失敗です。

5. ネストは2レベルまでにする

ネストは所有関係を表します。たとえば、`[REDACTED PATH]

推奨：

GET /v1[REDACTED PATH]
GET /v1/orders/1337/refunds

非推奨：

GET /v1[REDACTED PATH]

3レベル以上の深いネストは、リーフリソースがグローバルに一意なIDを持っていても、クライアントにすべての祖先IDを要求します。

払い戻しがID 7を持つなら、次のどちらかで十分です。

/refunds/7
/orders/1337/refunds/7

URLに3つ以上のIDが含まれていたら、平坦化を検討してください。注文が存在すれば、そのパスにユーザーIDを含める必要はありません。/orders/1337だけで独立したリソースとして扱えます。

6. フィルタリング、ソート、ページネーションはクエリパラメータに入れる

パスはリソースを識別し、クエリパラメータは取得方法を指定します。フィルターをパスに埋め込まないようにします。

推奨：

GET /v1/orders?status=active&sort=-created_at&limit=50&cursor=eyJpZCI6NDJ9
GET /v1/products?category=electronics&min_price=1000

非推奨：

GET /v1/orders/active
GET /v1/orders/sorted-by-date-desc
GET /v1/getOrdersByStatusAndDate

sort=-created_atのように、マイナス記号で降順を表す形式はJSON:API仕様に由来します。order=descのような追加パラメータを不要にできるのが利点です。

/orders/activeのようなパスは一見便利ですが、複数のフィルターを組み合わせるたびに新しいエンドポイントが必要になります。

ページネーションのパラメータも統一してください。

limit / cursor
page / per_page

どちらかを選び、すべてのコレクションで再利用します。APIページネーションガイドでは、カーソル方式とオフセット方式のトレードオフを詳しく解説しています。

7. パスにメジャーバージョンを記述する

APIバージョニングには、主に次の2つの方式があります。

パスセグメント：/v1/products
ヘッダー：Accept: application/vnd.myapi.v1+json

ヘッダーによるバージョニングは、バージョン間で同じURLが同じリソースを指し続けるため、より「純粋な」RESTと考えられます。Google API設計ガイドも、両方のアプローチが広く使われていると説明しています。

一方、パスバージョニングには運用上の利点があります。

すべてのログでバージョンを確認できる
ブラウザから直接テストできる
Varyを複雑に扱わずキャッシュできる
クライアントがバージョン指定を忘れにくい

バージョンヘッダーの欠落による「curlでは動くが、本番では失敗する」という問題は、デバッグを難しくします。

メジャーバージョンのみをパスに含め、/v1/を使用してください。/v1.2/のようなマイナーバージョンは避け、マイナーな変更は後方互換性のある追加としてリリースします。コンテンツネゴシエーションを含む詳しい比較は、APIバージョン管理戦略を参照してください。

8. リソースIDを不透明に扱う

次のような連番IDは、処理件数を推測させ、IDの列挙を容易にします。

/orders/41
/orders/42
/orders/43

攻撃者がIDを順番に試し、認証の隙間を探す可能性があります。不適切なオブジェクトレベル認証は、OWASP API Security Top 10で第1位に挙げられています。

推奨：

GET /v1/orders/ord_9f8e2a71b3
GET /v1/users/550e8400-e29b-41d4-a716-446655440000

非推奨：列挙が問題になる場合

GET /v1/orders/42
GET /v1/invoices/10883

Stripeのord_9f8e2a71b3のような、接頭辞付きのランダムIDは有効なパターンです。

推測しにくい
ログでリソース種別を判別しやすい
外部に安全に公開しやすい

ただし、不透明なIDは認証チェックの代わりにはなりません。認証・認可は必ず実装してください。内部では整数の主キーを使っても問題ありません。このルールは、URLで外部に公開するIDに関するものです。

9. 非CRUDアクションをコントローラーリソースとしてモデル化する

注文のキャンセル、支払いの再試行、メールの再送信など、通常のCRUDでは表現しにくい操作は必ず発生します。

推奨：

POST /v1/orders/42/cancel
POST /v1/payments/pay_88a1/retry

非推奨：

PATCH /v1/orders/42        { "status": "cancelled" }
POST  /v1/cancelOrder      { "orderId": 42 }

これは、動詞を使わないルールに対する限定的な例外です。動詞はパスの末尾に置き、対象リソースの下にスコープします。

PATCHでステータスだけを変更すると、状態マシンがフィールド更新の中に隠れてしまいます。注文のキャンセルによって、払い戻し、在庫の解放、通知の送信が発生するかもしれません。単なるフィールド書き込みに見せると、サーバーはペイロードを比較して意図を推測する必要があります。

/cancelのようなアクションエンドポイントなら、次のことを明確にできます。

操作の意図
アクション固有の権限
独立した監査証跡
キャンセル理由などの専用入力

10. ヘッダーとクエリパラメータの命名規則を統一する

カスタムヘッダーには、HTTPの慣習に合わせてハイフン区切りのパスカルケースを使用します。

Idempotency-Key
Request-Id

古いX-プレフィックスは使用しないでください。RFC 6648によって2012年に非推奨となっています。

ヘッダー名は通信上では大文字・小文字を区別しませんが、ドキュメントやSDKでは常に同じ表記を使います。

クエリパラメータは、JSONボディの命名規則に合わせます。ボディがスネークケースなら、クエリもスネークケースにします。

?min_price=1000&created_after=2026-01-01

?minPrice=1000のように別の規則を使うと、レスポンスではcreated_at、クエリではcreatedAfterという不統一が生まれます。最初の利用者が間違えれば、その後の利用者も同じ間違いをするでしょう。

ルールセット全体を一目で確認

#	ルール	推奨	非推奨
1	コレクションには複数形の名詞を使用する	`/products`, `/products/89`	`/getProducts`, `/productList`
2	パスに動詞を含めない	`DELETE /orders/42`	`POST /deleteOrder/42`
3	パスセグメントにはケバブケースを使用する	`/gift-cards`	`/giftCards`, `/gift_cards`
4	JSONの命名規則は一つに統一し、文書化する	`order_id` をどこでも使用	`orderId` と `order_id` を混在させる
5	ネストは最大2レベルまで	`/orders/1337/refunds`	`/users/42/orders/1337/refunds/7`
6	フィルターとページネーションはクエリパラメータに入れる	`?status=active&sort=-created_at`	`/orders/active`
7	パスにメジャーバージョンを含める	`/v1/products`	`/v1.2/products`, バージョンヘッダー
8	リソースIDは不透明にする	`/orders/ord_9f8e2a71b3`	`/orders/42`（公開、列挙可能）
9	アクションにはコントローラーパターンを使用する	`POST /orders/42/cancel`	`PATCH`で `{"status":"cancelled"}`
10	ヘッダーとパラメータの命名規則を統一する	`Idempotency-Key`, `?min_price=`	`X-IDEMPOTENCY_KEY`, `?minPrice=` を混在させる

大規模なコンベンションを適用する

Wikiにスタイルガイドを置くだけでは、APIの一貫性は保てません。一貫したAPIを運用するチームは、コードを書く前に設計し、その段階でコンベンションを適用します。これが実践的なAPIガバナンスの中心です。

Apidogでは、エンドポイントをスキーマファーストのビジュアルデザイナーで定義できます。パス、キャメルケース、パラメータ名が、コントローラーコード内の文字列ではなく、明示的な設計成果物になります。

共有コンポーネントを使えば、Pagination、Error、Moneyなどのスキーマを一度定義し、すべてのエンドポイントで再利用できます。新しいサービスごとにper_pageをpageSizeとして再発明する必要もありません。

設計はレビュー機能を備えたチームワークスペースで管理できます。そのため、3つのクライアントが統合した後ではなく、名前変更のコストが低い設計段階で/getUserOrdersのような問題を発見できます。

承認済みの仕様は、ドキュメント、モックサーバー、テストを駆動します。結果として、設計で承認された名前が、そのままチーム全体が出荷する名前になります。

Apidogをダウンロードして、次の新しいエンドポイントで無料で試してみてください。既存APIの改修は難しくても、新しいAPIで一貫性を保つことは難しくありません。

よくある質問

RESTのURLは複数形と単数形のどちらにすべきですか？

複数のインスタンスを持つリソース（/products、/orders、/users）には複数形を使います。複数形なら、コレクション（/orders）と個々のメンバー（/orders/42）の両方を自然に表現できます。

`[REDACTED PATH]を使用します。リソースモデリングの詳しい理由は、REST APIとは何かで基本原理から解説しています。

JSONフィールド名にはcamelCaseとsnake_caseのどちらが優れていますか？

どちらにも利点があります。

camelCase：JavaScriptを多用するユーザーに適している
snake_case：読みやすく、Python、Ruby、Stripeの公開APIと一致する

重要なのは、どちらか一方を選び、スタイルガイドに記載し、スキーマレビューで強制することです。エンドポイント間で命名規則が混在する方が、どちらを選ぶかより大きな問題になります。

APIバージョンはURLに入れるべきですか、それともヘッダーに入れるべきですか？

強力なハイパーメディア要件がない限り、パス（/v1/orders）を推奨します。パスバージョンは、クライアントが追加の設定をしなくても、ログ、キャッシュ、ブラウザテストに表示されます。

ヘッダーによるバージョニングはURLを安定させられますが、クライアントがヘッダーを忘れるとサイレントに失敗する可能性があります。メジャーバージョンだけを使用し、マイナーな変更は後方互換性のある追加としてリリースしてください。

REST APIパスで動詞が許容されることはありますか？

はい。非CRUDアクション用のコントローラーエンドポイントでは許容されます。

http POST /orders/42/cancel POST /payments/pay_88a1/retry

動詞はパスの最後に置き、対象リソースのスコープ内に配置します。メソッドはPOSTを使用します。

それ以外では、HTTPメソッドが動詞を伝え、パスは名詞だけで構成します。

カーソルベースページネーション対オフセットページネーション：APIでの選び方

Akira — Mon, 31 Aug 2026 11:21:30 +0000

あらゆるリストAPIは、最終的に同じ課題に直面します。200万件の注文を、クライアントが順番に閲覧できる形でどう分割するかです。オフセットページネーションなら、シンプルなSQLとわかりやすいページ番号を使えます。カーソルベースなら、安定した結果とページの深さに依存しないレイテンシーを得られますが、「47ページへ移動」のような機能は失われます。

Apidogを今すぐ試す

多くのチームは、チュートリアルで一般的なオフセットを選びます。しかし、注文テーブルが数百万行に達すると、4,000ページ目でタイムアウトが発生し、スクロール中に同じレコードが重複表示される問題も起こります。

この記事では、2つの方式の仕組み、オフセットが破綻する理由、StripeやSlackがカーソルを採用する背景、そしてApidogでチェーンリクエストを使って両方をテストする方法を解説します。

全体像を先に確認したい場合は、APIページネーションガイドも参照してください。

オフセットページネーションの仕組み

オフセットページネーションは、SQLのLIMITとOFFSETに直接対応します。クライアントはページ番号とページサイズを送信し、サーバーがSQLに変換します。

SELECT id, customer_id, total_cents, created_at
FROM orders
ORDER BY created_at DESC
LIMIT 25 OFFSET 50;

このクエリは、1ページ25行の注文リストで3ページ目を返します。

GET /v1/orders?page=3&per_page=25

典型的なレスポンスは次のとおりです。

{
  "data": [
    {
      "id": "ord_8821",
      "customer_id": "cus_1932",
      "total_cents": 4599,
      "created_at": "2026-08-30T14:22:07Z"
    }
  ],
  "page": 3,
  "per_page": 25,
  "total": 1848203,
  "total_pages": 73929
}

利点は明確です。

任意のページへ移動できる
合計件数や総ページ数を返しやすい
実装コストが低い

小規模な管理テーブルなら、オフセットは適切な選択です。REST APIにおけるページネーションでは、オフセット方式の構築手順を詳しく解説しています。

一方で、オフセットには本番環境で顕在化しやすい構造的な問題があります。

問題1：ページドリフト

オフセットは、ソート結果の先頭から行数を数えるだけです。クライアントがすでに見た行を追跡しません。そのため、リクエスト間にデータが追加・削除されると、ページの内容がずれます。

たとえば、作成日時の降順で1ページ目（1〜25行目）を表示している間に、新しい注文が3件追加されたとします。次のリクエストはOFFSET 25なので、最初のレスポンスにあった23〜25行目が26〜28行目へ押し出され、再び表示されます。これが重複です。

削除では逆の問題が起こります。1ページ目を読んでいる間に3行削除されると、OFFSET 25が未読の3行を飛ばしてしまいます。エラーにならないため、サイレントなデータ欠落になります。

月次レポートのように、データが変化しない用途では問題になりにくいでしょう。しかし、次の用途では重複や欠落につながります。

アクティビティフィード
同期API
書き込みが続く中でページ単位に処理するスクリプト

問題2：深いオフセットはスキップする行をすべてスキャンする

OFFSET 500000は、500,001行目へ直接移動する操作ではありません。データベースは50万件のインデックスエントリをたどって破棄し、その後に25行を返します。コストはオフセット値nに比例し、O(n)で増加します。

200万行のPostgresordersテーブルにcreated_atのインデックスがある場合、目安は次のとおりです。

LIMIT 25 OFFSET 0：25件のインデックスエントリを読み取る。数ミリ秒。
LIMIT 25 OFFSET 100000：100,025件を読み取り、100,000件を破棄する。数十ミリ秒。
LIMIT 25 OFFSET 1500000：150万件を読み取る。数百ミリ秒を消費し、1ページのためにバッファとCPUを使う。

Markus Winand氏のUse The Index, Lukeにあるno-offsetの記事では、クエリプランを使ってこのコストを実証しています。

本番環境では、高オフセットのリクエストがスロークエリログを占有します。公開APIをページ単位で巡回するクローラーが1つあるだけで、p99レイテンシーが倍増することもあります。

カーソルベースページネーションの仕組み

カーソルベースページネーションは、キーセットページネーションとも呼ばれます。行数をスキップする代わりに、「特定のレコードの後にある行」を要求します。

カーソルはクライアントが最後に見た行を識別するため、サーバーは次のバッチへ直接シークできます。

SELECT id, customer_id, total_cents, created_at
FROM orders
WHERE (created_at, id) < ('2026-08-30T14:22:07Z', 'ord_8821')
ORDER BY created_at DESC, id DESC
LIMIT 25;

重要なのは、ソートキーを2列にしている点です。created_atだけでは一意とは限りません。同じミリ秒に複数の注文が作成される可能性があるためです。一意でないソートキーを使うと、ページ境界でレコードの重複や欠落が起こります。

idをタイブレーカーとして追加し、(created_at, id)の複合インデックスを作成すれば、順序が決定的になります。データベースは境界へ直接シークして25件だけを読み取るため、1ページ目でも60,000ページ目でもコストはほぼ一定です。

ただし、APIでこれらの値をそのまま公開するべきではありません。通常は、ソートキーを不透明なトークン（多くの場合base64）にエンコードします。

GET /v1/orders?limit=25&cursor=eyJjcmVhdGVkX2F0IjoiMjAyNi0wOC0zMFQxNDoyMjowN1oiLCJpZCI6Im9yZF84ODIxIn0

不透明性は単なる難読化ではなく、API設計上の利点です。クライアントがカーソルを解析できなければ、次の変更を内部で行えます。

ソートキーの変更
シャードヒントの追加
ストレージエンジンの変更

クライアントとの契約は、「サーバーが返したカーソルを、そのまま次のリクエストに返す」だけです。

トレードオフとして、47ページ目へ直接移動する機能はありません。カーソルが知っているのは「この行の後」だけなので、クライアントは1ページずつ進みます。合計件数も別途カウントクエリが必要です。数百万レコードのAPIページネーションを設計するためのガイドでは、スケーリングの考え方をさらに解説しています。

トレードオフの概要

項目	オフセットページネーション	カーソルベースページネーション
任意のページへのジャンプ	可能（任意のページ番号）	不可（順次移動のみ）
合計件数 / ページ数	含めるのが容易	別途カウントクエリが必要
深いページのパフォーマンス	O(n)、深さとともに劣化	どの深さでも1ページあたりO(1)
書き込み時の安定性	ドリフト（重複と欠落）	安定（行に固定される）
構築コスト	非常に低い	中程度（エンコーディング、タイブレーカー、インデックス設計）
順序付けの要件	任意のORDER BYが機能	一意でインデックス付きのソートキーが必要
ページURLのキャッシュ	容易（URLは予測可能）	困難（カーソルは移動ごとに異なる）
クライアント側の複雑さ	低い	低い（エンベロープが明確であれば）

カーソル方式では、決定的なソートが必須です。たとえば、statusのように変更可能で一意でないカラムでソートを許可すると、キーセットロジックはすぐに複雑になります。

オフセットは柔軟なORDER BYを許容しますが、カーソルは一意でインデックス付きのソートキーを必要とします。

どちらを選ぶべきか？

ページネーション方式は、データの消費方法で決めます。

管理テーブルとダッシュボード：オフセット

数千行程度の内部ツールで、人間がページ番号をクリックし、「1,848件の結果」のような表示を必要とする場合です。データの変化が少なく、ページが浅いなら、ページジャンプを実現できるオフセットが有利です。

無限スクロールフィード：カーソル

フィードの47ページ目へ移動するユーザーはいません。ユーザーは「さらに読み込む」を繰り返し、データは継続的に追加されます。重複表示も目立つため、カーソルが適しています。

公開API：カーソル

コンシューマーの挙動を制御できないため、全ページを巡回するクライアントが現れます。オフセットでは深いページが問題になりますが、カーソルなら各ページのコストを抑えられます。また、不透明なトークンの背後で内部実装を変更できます。

REST APIページネーションガイドでは、URLとヘッダーの慣例を詳しく解説しています。

エクスポートと同期ジョブ：カーソル

200万件の注文を取得するバッチジョブには、次の2つが必要です。

同時書き込みがあっても行を見逃さないこと
ページごとのコストが一定であること

オフセットはどちらも保証しません。カーソルなら、ジョブが140万行目で停止しても、カーソルを使ってその位置から再開できます。

経験則としては、次のように考えるとよいでしょう。

小規模で人間が閲覧し、件数やページ移動が必要：オフセット
大規模、リアルタイム、または公開API：カーソル

実際のAPIがどのように対応しているか

Stripe

Stripeは完全にカーソルベースです。リストエンドポイントはstarting_after（オブジェクトID）とlimitを受け付け、レスポンスにhas_moreを含めます。次ページを取得するには、最後に受け取った課金オブジェクトのIDを渡します。Stripeのページネーションドキュメントにパターンが示されています。

Stripeの書き込み量を考えると、合計件数をレスポンスに含めていない点も重要です。

GitHub REST API

GitHubのREST APIは、ほとんどのエンドポイントでpageとper_pageを公開し、Linkヘッダーで次ページや最終ページを示します。

ただし、GitHubのページネーションドキュメントでは、クライアントがURLを組み立てるのではなく、LinkヘッダーのURLに従うよう推奨しています。新しいエンドポイントはカーソルへ移行しています。大規模なリポジトリで深いオフセットを巡回すると、パフォーマンスに悪影響があるためです。

Slack

SlackはWeb APIをカーソルページネーションへ移行し、現在は新しいメソッドでこの方式を採用しています。

conversations.historyなどのメソッドはresponse_metadata.next_cursorを返します。空のカーソル文字列は、終端に到達したことを示します。Slackのページネーションドキュメントに詳細があります。

高トラフィックAPIの傾向は明確で、カーソル方式へ向かっています。

レスポンスエンベロープの設計

カーソルAPIの使いやすさは、レスポンスエンベロープで決まります。予測可能で一貫した形式にしましょう。

{
  "data": [
    {
      "id": "ord_8846",
      "customer_id": "cus_2201",
      "total_cents": 12900,
      "created_at": "2026-08-30T16:01:44Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wOC0zMFQxNjowMTo0NFoiLCJpZCI6Im9yZF84ODQ2In0"
}

堅牢な設計には、次の4つのルールが役立ちます。

常にhas_moreを返す。ページが短いことだけを理由に、クライアントが終端と判断しないようにする。取得後のフィルタリングで、途中のページが短くなることもある。
最終ページのnext_cursorはnullにし、その仕様を文書化する。空文字列を使うSlack方式でもよいが、形式を混在させない。
無効なカーソルは、空の200レスポンスではなく400で拒否する。破損したカーソルはクライアントのバグとして明示する。
ソートキー以外の情報をエンコードする場合は、カーソルに署名またはバージョンを付ける。将来のスキーマ移行で役立つ。

Apidogで両方のスタイルをテストする

ページネーションのバグは、最後のページ、空のページ、削除されたアンカー行などの境界に潜みます。手動クリックだけでは見つけにくい問題も、チェーンされたテストシナリオなら検証できます。Apidogは、このようなワークフローのテストに適しています。

カーソルエンドポイント

2ステップのテストシナリオを作成します。

最初のリクエストでカーソルを抽出する

レスポンス後処理にJSONPath$.next_cursorを設定し、nextCursorなどの変数へ保存します。Apidogでは、レスポンスパネルからJSONPathを直接コピーできます。詳しくは、JSONPathでアサーションを設定し変数を抽出する方法を参照してください。

次ページ以降をループする

2番目のリクエストをForEachまたはループステップで囲み、{{nextCursor}}をカーソルパラメータとして渡します。各イテレーションで$.next_cursorを再抽出し、has_moreがfalseになったら終了します。

各ページで、次のアサーションを追加します。

前ページとidが重複していない
ページサイズがlimitを超えていない

オフセットエンドポイント

同じ構造をカウンター変数で実装できます。

pageをインクリメントする
最終ページまでdataの長さがper_pageと一致することを確認する
全ページを通じてtotalが一貫していることを確認する

エッジケース

各ケースを独立したステップにし、明示的なアサーションを追加します。

空のページ：0行に一致するフィルターを指定し、dataが[]、has_moreがfalse、ステータスが200であることを確認する。
無効なカーソル：cursor=not-a-real-cursorを送信し、ステータスが400で、機械可読なエラーコードが返ることを確認する。
削除されたアンカー行：注文を作成してカーソルを取得し、その注文を削除してからカーソルを使用する。エラーにならず、正しい位置から処理が継続することを確認する。

キーセット比較ではアンカー行の存在が不要なため、このケースを自然に処理できます。

ローカルでシナリオが通ったら、マージごとにCIで実行しましょう。Apidogを無料でダウンロードすれば、ループやアサーションを含むカーソルウォークシナリオを30分以内に実行できます。

よくある質問（FAQ）

カーソルページネーションは常に優れているのか？

いいえ。適度なデータセットに対してページ番号、合計件数、ランダムアクセスが必要な内部管理ツールでは、オフセットの方が適しています。

一方、データセットが大規模、書き込みが頻繁、またはAPIが公開されている場合は、カーソルが適しています。典型的な失敗は、公開リストAPIにオフセットを採用し、ローンチ後にO(n)のコストへ気づくことです。

カーソルページネーションで合計件数を取得するには？

同じフィルターで、別途SELECT COUNT(*)を実行します。提供方法は次のいずれかです。

専用のエンドポイント
include_count=trueのようなオプトインパラメータ

カウントは積極的にキャッシュしましょう。1分ごとに更新される概算値でも、多くのUI要件を満たせます。Stripeは合計件数を完全に省略しており、クライアントが実際にどれだけ必要としているかを考える材料になります。

1つのエンドポイントで両方の方式を提供できるか？

可能です。GitHubは移行期間中、実質的に両方を提供しています。

ただし、新しいAPIでは避けるのが無難です。2つの方式を提供すると、エッジケース、テストマトリックス、クライアントの混乱がそれぞれ増えます。エンドポイントごとに1つの方式を選びましょう。

新規に契約を設計する場合は、REST APIページネーションガイドを参考に、API全体でパラメータ名を統一してください。

カーソルのアンカー行が削除されたらどうなるか？

キーセットページネーションでは、基本的に問題ありません。

WHERE (created_at, id) < (?, ?)の比較は、アンカー行が存在することを要求しません。データベースは境界位置へシークし、そこから処理を続行します。

これは「行ルックアップとしてのカーソル」設計の利点です。ユーザーが問題を発見する前に、Apidogのテストシナリオで必ず検証しましょう。

REST APIエラー処理ベストプラクティス：ステータスコード、RFC 9457、リトライ可能なエラー

Akira — Mon, 31 Aug 2026 10:54:40 +0000

REST APIのエラー処理を設計する：ステータスコード、Problem Details、再試行、テスト

APIのエラー応答は契約の一部です。クライアントは応答を解析し、リトライロジックはそれに応じて分岐し、サポートエンジニアは午前2時にエラーをgrepで検索します。それにもかかわらず、正常系だけを詳細に設計し、エラー処理をフレームワークのデフォルトに任せるチームは少なくありません。その結果、1つのAPIに複数のエラー形式が存在したり、"success": falseを含む200応答が返ったり、データベーススキーマを漏らすスタックトレースが公開されたりします。

今すぐApidogを試す

このガイドでは、RESTサービスのエラー処理を契約として設計する方法を解説します。適切なHTTPステータスコード、RFC 9457 Problem Detailsによるエラー形式の統一、機械可読コードと人間向けメッセージの分離、再試行可能性の明示、機密情報の除外、そしてApidogを使った失敗パスのテストが対象です。

1. エラーボディより先にステータスコードを決める

HTTPは、エラーセマンティクスの第一層を提供します。RFC 9110では、4xxはクライアント側の問題、5xxはサーバー側の問題を表します。汎用クライアント、プロキシ、キャッシュ、リトライライブラリは、JSONを読む前にこの区分で動作を決めるため、エラーボディを設計する前にステータスコードを確定してください。

設計時はMDNのHTTPステータスコードリファレンスも参照し、迷いやすいケースには次の表を使います。

状況	使用	非推奨	理由
壊れたJSON、誤ったContent-Type、必須フィールドの欠落	400 Bad Request	422	サーバーがリクエストを解析・理解できない
整形式だが意味論的に不正（金額が負、未対応通貨など）	422 Unprocessable Content	400	構文は正しいが値が不正
認証情報がない、期限切れまたは無効なトークン	401 Unauthorized	403	クライアントが身元を証明していない。`WWW-Authenticate`を送信する
認証済みだが権限が不足	403 Forbidden	401	身元は確認済みだがアクセスを拒否した。再認証では解決しない
リソースが存在しない、または存在を確認させたくない	404 Not Found	410	安全なデフォルト。不正なプロービングからリソースを隠せる
リソースが意図的かつ永続的に削除済み	410 Gone	404	クライアントやクローラーに参照の削除を促す
重複キー、古いバージョン、編集の衝突	409 Conflict	400	リクエストは有効だが現在のリソース状態と衝突する
クライアントがレート制限を超過	429 Too Many Requests	503	クライアントが適切に後退できるよう、常に`Retry-After`を含める
コード内の未処理例外	500 Internal Server Error	502	サーバー自体が失敗した
アップストリームがゲートウェイに不正なデータを返した	502 Bad Gateway	500	障害はエッジではなくダウンストリームにある
サーバーが過負荷またはメンテナンス中	503 Service Unavailable	500	定義上、一時的な障害。可能であれば`Retry-After`を追加する
アップストリームがタイムアウトした	504 Gateway Timeout	500	遅い依存関係と壊れたコードを区別できる

特に重要なのは次の2点です。

401と403はセキュリティ境界であり、スタイルの問題ではない 未認証の呼び出し元に403を返すと、リソースの存在を推測される可能性があります。
429にはRetry-Afterを付ける ヘッダーがなければ、クライアントはタイトループで再試行する可能性があります。

レート制限のヘッダー計算やアルゴリズムについては、APIレート制限の実装方法も参照してください。

2. RFC 9457 Problem Detailsでエラー形式を統一する

ステータスコードを正しく設定したら、すべてのエラーで同じメディアタイプとスキーマを使います。標準的な選択肢は、application/problem+jsonで返すRFC 9457 Problem Detailsです。

Problem Detailsのコアメンバーは次の5つです。

type: エラーカテゴリを識別するURI
title: 短い人間向けの要約
status: HTTPステータスコード
detail: このリクエストで何が問題だったか
instance: この障害インスタンスを識別するURI

それ以外の情報は、独自の拡張メンバーとして追加します。RFC 9457解説では、各メンバー、レジストリルール、RFC 7807からの変更点を詳しく説明しています。

たとえば、決済エンドポイントのバリデーションエラーは次のように返せます。

POST /v1/payments HTTP/1.1
Content-Type: application/json

{ "amount": -1400, "currency": "USD", "source": "card_8xKt2" }

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://api.example.com/problems/validation-error",
  "title": "リクエストの検証に失敗しました",
  "status": 422,
  "detail": "1つ以上のフィールドの検証に失敗しました。",
  "instance": "/v1/payments/requests/req_9f3c1a7b",
  "code": "PAYMENT_VALIDATION_FAILED",
  "errors": [
    {
      "field": "amount",
      "code": "AMOUNT_NOT_POSITIVE",
      "message": "amountはマイナーユニットで正の整数である必要があります"
    }
  ],
  "request_id": "req_9f3c1a7b"
}

errors[]は拡張メンバーです。フロントエンドはこれを使って、曖昧なエラーバナーではなく、該当するフォームフィールドにエラーを表示できます。

クライアントがプログラムで処理できるように、フィールドパスはJSON Pointerまたはドットパスのどちらかに統一し、安定させてください。

また、アプリケーションのハンドラーだけでなく、フレームワークやゲートウェイが生成するエラーにも同じ形式を適用します。ハンドラーではProblem Details、ロードバランサーではHTMLという状態になると、クライアントは2種類のパーサーを実装しなければなりません。

3. 機械可読コードと人間向けメッセージを分離する

codeとmessageを併用するのは意図的です。両者の対象読者が異なるため、1つの文字列にまとめないでください。

機械可読コード

AMOUNT_NOT_POSITIVE、CURRENCY_UNSUPPORTED、IDEMPOTENCY_KEY_REUSEDのようなコードはAPI契約です。クライアントが分岐に使うため、次の条件を満たす必要があります。

安定している
ドキュメント化されている
列挙可能である
意味を変更しない

クライアントに文章を解析させてはいけません。たとえば、if (message.includes("positive"))のような実装は、文言の修正を破壊的変更にしてしまいます。

人間向けメッセージ

メッセージはログを読む開発者や利用者のためのものです。何が失敗し、どう修正すればよいかを明確にします。

"invalid amount"よりも、次のようなメッセージの方が有用です。

amountはマイナーユニットで正の整数である必要があります

ローカライズする場合はメッセージだけを翻訳し、コードは変更しません。

APIコンシューマーに自律エージェントが含まれる現在、この分離はさらに重要です。LLMベースのクライアントは、構造化され自己記述的なエラーからより適切に回復できます。詳しくはAIエージェント向けAPIエラー設計を参照してください。

4. エラー応答から機密情報を除外する

エラー応答は攻撃者の偵察チャネルになります。エラーミドルウェアでは、次の情報がクライアントに届かないようにします。

スタックトレース、クラス名、ファイルパス
生SQL、クエリ断片、ORMエラー
内部ホスト名、IPアドレス、ポート、サービス名
ライブラリのバージョン、フレームワークのバナー
例外テキストに含まれる秘密情報、トークン、接続文字列
ユーザーアカウントの存在有無ログインやパスワードリセットでは、成功・失敗の応答を対称的に保つ

基本パターンは次のとおりです。

境界で例外をすべて捕捉する
リクエストIDとともに完全な例外をサーバー側へ記録する
同じIDを持つ汎用Problem Detailsを返す

クライアントには次のような情報だけを返します。

{
  "detail": "内部エラーが発生しました",
  "request_id": "req_51ad0"
}

ログには詳細な原因を残し、サポート担当者はrequest_idで両者を結び付けます。

5. エラーを再試行可能または終端として定義する

すべてのエラーは、クライアントが次に知りたい問いに答えるべきです。

もう一度試すべきか？

一般的なデフォルトは次のとおりです。

429、502、503、504: 指数バックオフとジッターを付けて再試行
500: 通常は慎重な1回の再試行
その他の多くの4xx: 終端エラーとして再試行しない

401、403、404、422を同じリクエストで繰り返しても、クォータを消費しログを汚すだけです。

タイムアウトには注意が必要です。クライアントがタイムアウトした後でも、サーバー側では処理が成功している可能性があります。変更を伴うエンドポイントでは冪等性キーを受け入れ、リトライによる二重請求や二重作成を防いでください。

再試行可能性は拡張メンバーで明示できます。

{
  "type": "https://api.example.com/problems/rate-limited",
  "title": "リクエストが多すぎます",
  "status": 429,
  "code": "RATE_LIMITED",
  "retryable": true,
  "retry_after_seconds": 30
}

retryableを使えば、ステータスコードのデフォルトを上書きできます。たとえば、再試行すると状態が壊れる特定の500サブコードを終端エラーとして扱うケースです。

この仕様を一度文書化すれば、各クライアントSDKで同じバックオフ動作を実装できます。

6. 相関IDとエラー契約をバージョン管理する

後から追加すると高くつくため、次の2点を最初に決めます。

リクエストIDを全リクエストに付与する

受信したX-Request-Idを利用する、または生成する
すべてのログ行に記録する
すべてのエラーボディにrequest_idとして返す
分散システムではW3Cのtraceparentもサービス間で伝播する

顧客がエラーをサポートチケットに貼り付ければ、request_idによって1時間のログ調査を1回のクエリに短縮できます。

エラー契約をAPIと同じように管理する

次の変更は通常、安全です。

新しい拡張メンバーの追加
新しいエラーコードの追加

一方、次の変更は破壊的です。

errors[].fieldの名前変更
既存コードの意味の変更
アドホック形式からProblem Detailsへの移行

type URIを安定した識別子として使い、古い型URIは永続的に維持します。新しいセマンティクスには新しい型URIを導入し、未知の拡張メンバーや未知のコードは無視して処理を継続する、とドキュメントに明記してください。この前方互換性のルールにより、v2を待たずに契約を進化させられます。

7. Apidogで全エラーパスをテストする

エラー契約は、実行しなければ腐敗します。正常系はデモで常に実行されますが、422ブランチは顧客が実際に遭遇するまで放置されがちです。

解決策は、失敗ケースをテストスイートの第一級のシナリオにすることです。Apidogでは、サーバー側とクライアント側の両方を検証できます。

サーバーサイドのテストシナリオ

エンドポイントごとに失敗ケースを作成します。

認証情報なし: 401
権限不足: 403
負の金額: errors[0].codeがAMOUNT_NOT_POSITIVEの422
バーストトラフィック: Retry-After付きの429

Apidogのビジュアルアサーションを使えば、スクリプトなしで次を検証できます。

ステータスコード
レスポンスヘッダー
Problem Detailsの各フィールド
JSONスキーマ全体

エラー形式のずれはCIで検出し、本番環境で発見しないようにします。アサーションのパターンについては、APIアサーションガイドを参照してください。

クライアントサイドのモックサーバー

フロントエンドチームやSDKチームは、バックエンドが失敗レスポンスを生成する前から、4xx・5xxへの対応を実装できる必要があります。

Apidogのモックサーバーは、API仕様からProblem Detailsを返せます。たとえば次のケースをシミュレートできます。

Retry-After: 120付きの503
二重送信時の409
errors[]を含む完全なバリデーションエラー

これにより、クライアントの表示や再試行動作を確認できます。手作業のExpressスタブや、バックエンドコードを一時的にコメントアウトする必要はありません。

エラー契約を設計し、シナリオとモックとして定義し、両方をCIに組み込みましょう。Apidogをダウンロードし、無料で試せます。既存のOpenAPI仕様をインポートするだけで、数分でモック可能なエラー応答を作成できます。

FAQ

バリデーションエラーには400と422のどちらを使うべきですか？

リクエスト形式が不正でサーバーが理解できない場合は400を使います。無効なJSON、誤ったContent-Type、必須フィールドの欠落などが該当します。

リクエストを解析できるものの、値がドメインルールに違反する場合は422を使います。負の支払い金額や未対応の通貨などです。

422は「データを修正してください」、400は「リクエスト形式を修正してください」という診断情報を伝えられます。どちらを選ぶ場合も、すべてのエンドポイントで一貫させてください。

`application/problem+json`とは何ですか？

RFC 9457が定義する、HTTP API向けProblem Detailsの標準メディアタイプです。このContent-Typeの応答には、type、title、status、detail、instanceと、errors[]のような独自拡張を含められます。

登録済みのメディアタイプを使うことで、汎用クライアントやミドルウェアはカスタム設定なしでエラーを認識できます。詳しくはRFC 9457解説を参照してください。

クライアントはどのHTTPエラーを自動的に再試行すべきですか？

429、502、503、504は、指数バックオフとジッターを付けて再試行します。Retry-Afterがあれば、その値に従ってください。

500は、慎重な1回の再試行に限定します。その他の4xxは通常、再試行しません。同じリクエストは毎回同じように失敗するためです。

変更を伴うエンドポイントでは、冪等性キーと組み合わせて、リプレイによる二重請求や二重作成を防ぎます。

バックエンドを壊さずにAPIエラー応答をテストするには？

エラーをシミュレートします。

クライアントをApidogモックサーバーに接続し、仕様から正確な4xx・5xxレスポンスを返して、表示と再試行動作を確認します。サーバー側では、無効なペイロード、認証情報の欠落、バーストトラフィックを送信するテストシナリオを作成し、ステータスコード、ヘッダー、エラーボディのスキーマを検証します。

両方をCIで実行すれば、手動で失敗を強制しなくても、エラー契約を維持できます。

APIリトライロジックと指数関数的バックオフ：効果的なパターン

Akira — Mon, 31 Aug 2026 10:51:16 +0000

本番環境で安全なリトライを実装する方法

午前2時に支払いAPIが失敗したとき、その原因が一時的なネットワーク障害、レート制限、サーバー停止のどれかによって、リトライが決済を救うか、顧客への二重請求を招くかが決まります。リトライは分散システムで最も一般的なレジリエンスパターンですが、実装を誤ると短時間の障害を長時間の障害へ拡大させます。本記事では、リトライ対象のステータスコード、フルジッター付き指数バックオフ、Retry-After、冪等性キー、リトライバジェット、サーキットブレーカー、そしてApidogを使った障害テストを解説します。

今すぐApidogを試す

安易なリトライが障害を悪化させる理由

1秒間に1,000リクエストを処理するサービスが5秒間停止し、すべてのクライアントが即座に3回リトライするとします。通常の1,000rpsに加えてリトライが殺到し、サーバーは約4,000rpsを処理することになります。すでに過負荷のサーバーは完全に停止し、クライアントはさらにリトライします。

このフィードバックループはリトライストームと呼ばれます。サーバー復旧時にクライアントが同期して押し寄せる現象は、雷鳴の群れ（thundering herd）です。バックオフなしのリトライは負荷を増幅し、元の障害が解消した後も停止を長引かせます。

よくある設計ミスは次の2つです。

遅延がない： 即時リトライで障害中のサーバーに負荷を追加する。
固定遅延： すべてのクライアントが1秒待つため、同時に再接続する。

解決策は「リトライしない」ことではありません。リトライ対象を選び、ランダムな遅延を増やし、追加負荷に上限を設けることです。

リトライする障害、リトライしない障害

バックオフを計算する前に、リトライ判断のテーブルを用意します。サーバーが無効と判断したリクエストを再送しても、容量を消費し、ログを汚すだけです。

リトライする信号

信号	意味
`429 Too Many Requests`	レート制限に達した。間隔を空けて再試行する。
`502 Bad Gateway`	アップストリームが不正な応答を返した。一時的なことが多い。
`503 Service Unavailable`	サーバーが過負荷、または再起動中。
`504 Gateway Timeout`	アップストリームの依存関係が遅すぎた。
Connection reset、DNS failure、socket timeout	リクエストがサーバーに届かなかった可能性がある。

504 Gateway Timeoutには注意が必要です。ゲートウェイが待機を諦めても、オリジンはリクエストを処理していた可能性があります。特に書き込み処理では、後述する冪等性が重要です。

決して自動リトライしない信号

信号	意味
`400 Bad Request`	ペイロードが不正。次回も不正なまま。
`401 Unauthorized`	認証情報が間違っている、または期限切れ。トークンを更新する。
`403 Forbidden`	権限がない。リトライしても権限は付与されない。
`422 Unprocessable Entity`	バリデーションエラー。タイミングではなくデータを修正する。

基本ルールは次のとおりです。

サーバーの状態やネットワークが原因ならリトライする。
リクエストの内容が原因なら即座に失敗させる。
429はリトライ可能だが、クライアント側の送信レートを改善すべき信号でもある。

指数バックオフとジッター

指数バックオフでは、リトライごとに待機時間を増やします。一般的には前回の2倍です。

delay = base * 2^retry_count

ベースを500msにすると、待機時間は次のようになります。

0.5秒、1秒、2秒、4秒、8秒

遅延が長くなりすぎないよう、上限を設定します。

delay = min(cap, base * 2^retry_count)

たとえば上限を30秒にします。

ただし、これだけでは同期の問題は解決しません。5,000台のクライアントが同時に失敗すると、全クライアントが0.5秒後、1秒後、2秒後に再接続します。負荷の波が発生する点は変わりません。

そこで、待機時間をランダム化するジッターを加えます。AWSの「指数バックオフとジッターの分析」では、競合するクライアントをシミュレーションし、ジッターなしでは呼び出しがクラスター化することを示しています。フルジッターは、呼び出し回数を抑えながら完了時間も短くできます。

delay = random_between(0, min(cap, base * 2^retry_count))

ゼロから上限まで分散させることで、クライアントを待機ウィンドウ全体に均等に配置できます。

AWSの分析では、次の方式も比較されています。

イコールジッター：半分を固定、半分をランダム化
非相関ジッター
フルジッター

フルジッターと非相関ジッターが優れ、実装が簡単なフルジッターをデフォルトにしやすい結果でした。別の測定結果がない限り、フルジッターを使うのがよいでしょう。

`Retry-After`を尊重する

バックオフはクライアント側の推測です。一方、サーバーはレート制限の解除時刻やメンテナンス終了時刻を把握しています。

429および503では、サーバーがRetry-Afterヘッダーを返すことがあります。値は秒数またはHTTP日付です。

HTTP/1.1 429 Too Many Requests
Retry-After: 12

ヘッダーが存在する場合は、計算したバックオフより優先します。ただし、次の制限は必ず適用してください。

最大待機時間の上限
最大リトライ回数
不正または極端に大きい値への防御

たとえばRetry-After: 86400を無制限に受け入れると、ワーカーが1日停止する可能性があります。

POSTをリトライする前提条件：冪等性

GET、PUT、DELETEは契約上、冪等な操作です。同じリクエストを複数回送っても、最終的な状態は同じになります。

一方、POSTは通常、冪等ではありません。

POST /v1/payments

このリクエストがタイムアウトしても、サーバー側では決済が完了している可能性があります。その状態でリトライすると、2回目の支払いが作成され、二重請求につながります。

解決策は冪等性キーです。各論理操作に対してクライアントがUUIDなどの一意なIDを生成し、ヘッダーで送信します。サーバーは最初の応答とキーを保存し、同じキーの重複リクエストには保存済みの応答を返します。Stripeの冪等なリクエストもこの方式です。

重要なルールは2つあります。

同じ操作には同じキーを使う。 1回の決済に対するすべてのリトライで同じキーを再利用する。
最初の送信前にキーを生成する。 リトライループ内で生成すると、毎回新しい操作として扱われる。

呼び出し先が冪等性キーをサポートしていない場合、非冪等な書き込みを自動リトライしてはいけません。失敗を返し、人間または照合ジョブに判断させます。

リトライバジェットとサーキットブレーカー

バックオフは「いつ」リトライするかを決めますが、「何回」リトライするか、全体にどれだけ負荷を追加するかまでは制限しません。

また、APIゲートウェイが3回、サービスクライアントも3回リトライすると、ユーザーの1クリックが最大9リクエストに増えることがあります。

リトライバジェット

「リクエストごとに3回」ではなく、次のように追加負荷全体で制限します。

スライディングウィンドウ内で、リトライによる追加トラフィックを最大10%に抑える。

予算を使い切ったら、以降の失敗は即座に返します。これにより、同時障害が発生してもリトライの増幅を制限できます。LinkerdとEnvoyは、リトライバジェットを標準機能として提供しています。

サーキットブレーカー

サーキットブレーカーは、依存先ごとの失敗率を監視します。しきい値を超えるとブレーカーを開き、ネットワークへ接続せずに即座に失敗させます。

クールダウン後は少数のプローブリクエストを送り、依存先が復旧していればブレーカーを閉じます。

バックオフ：リトライを遅らせる
サーキットブレーカー：リトライを止める

長時間の障害に備えるなら、両方を組み合わせます。バックオフだけでは、最終的にすべてのリクエストを送信してしまうためです。

Pythonで実装する本番向けリトライ

次の例では、以下をまとめて実装しています。

リトライ可能なステータスのフィルタリング
フルジッター
Retry-After
冪等性キー
最大リトライ回数

import random
import time
import uuid

import requests


RETRYABLE = {429, 502, 503, 504}
BASE = 0.5  # seconds
CAP = 30.0  # ceiling on any single delay
MAX_RETRIES = 5


def create_payment(payload):
    idempotency_key = str(uuid.uuid4())  # one key per logical payment
    headers = {"Idempotency-Key": idempotency_key}

    for retry_count in range(MAX_RETRIES + 1):
        try:
            resp = requests.post(
                "https://api.acmepay.com/v1/payments",
                json=payload,
                headers=headers,
                timeout=10,
            )

            if resp.status_code < 400:
                return resp.json()

            if resp.status_code not in RETRYABLE:
                resp.raise_for_status()  # 400/401/403/422: fail fast

            retry_after = resp.headers.get("Retry-After")

        except (requests.ConnectionError, requests.Timeout):
            retry_after = None  # ネットワーク障害：バックオフへ移行

        if retry_count == MAX_RETRIES:
            raise RuntimeError(
                "payment failed after all retries"
            )  # すべてのリトライ後に支払いが失敗しました

        if retry_after and retry_after.isdigit():
            delay = min(CAP, float(retry_after))
        else:
            delay = random.uniform(
                0,
                min(CAP, BASE * 2 ** retry_count),
            )

        time.sleep(delay)

実装上のポイントは次のとおりです。

冪等性キーはループの外で1回だけ生成する。
Retry-Afterは計算したバックオフより優先する。
サーバー指定の待機時間にも上限を適用する。
リトライ不可のステータスはすぐに失敗させる。
Retry-AfterのHTTP日付形式を使う場合は、その形式も解析する。

JavaScriptでは、axios-retryのretryConditionとretryDelayフックで同じ設計を実装できます。ステータスコードの判断テーブルは変わりません。

本番障害の前にリトライをテストする

ハッピーパスだけをテストし、503やタイムアウトの分岐を本番障害で初めて実行するチームは少なくありません。Apidogを使えば、失敗シナリオを事前に再現できます。

モックサーバーで障害を再現する

Apidogのスマートモックで、/v1/paymentsのようなエンドポイントを定義し、応答をシナリオごとに設定します。

最初の2回は503、3回目は200
Retry-After: 5付きの429
クライアントのタイムアウトを発生させる15秒の遅延

クライアントをモックURLへ向け、各ケースでリトライループが期待どおり動作するかを確認します。

テストシナリオで動作をアサートする

Apidogのテストシナリオでは、リクエストをアサーションやタイミングチェックと連結できます。次の項目を検証しましょう。

最終的にリクエストが成功すること
合計経過時間がバックオフの想定範囲内であること
冪等性キーによってリソースが1つだけ作成されること

シナリオをCIに組み込めば、リトライロジックを障害発生時ではなく、コミットごとに検証できます。

「リトライを追加した」だけでは不十分です。レート制限中や半壊状態の依存先に対しても、クライアントが安全に動作することを証明する必要があります。Apidogを無料でダウンロードすれば、約10分で失敗するモックサーバーを用意できます。

FAQ

429をリトライすべきですか？

はい。ただし、サーバーが返した唯一の明確な指示として扱ってください。

Retry-Afterを読み取り、少なくとも指定時間待ちます。ヘッダーがなければ、フルジッター付き指数バックオフへフォールバックします。

繰り返し429が発生する場合は、通常動作と見なしてはいけません。クライアント側のスロットリングやキャッシュで、リクエストレート自体を下げる必要があります。

フルジッターとは何ですか？

各リトライの遅延を、ゼロから指数上限までの一様乱数で決める方式です。

random(0, min(cap, base * 2^n))

多数のクライアントが同時に再試行する波を防ぎます。AWSのシミュレーションでは、単純なバックオフやイコールジッターより、総呼び出し数と完了時間の両方で優れた結果になりました。

POSTリクエストをリトライしても安全ですか？

実際に冪等である場合だけ安全です。通常のPOSTでは、サーバーが重複排除できる冪等性キーを送信してください。

キーがなければ、タイムアウト後のリトライによって支払い、注文、記録などが重複する可能性があります。書き込みAPIを呼び出すAIエージェントでも同じ問題が起こります。必要なパターンは、キー付き書き込み、上限付きリトライ、サーキットブレーカーです。

何回リトライすべきですか？

多くの一時障害には、3〜5回の試行で対応できます。それ以上では成功率が伸びにくい一方、負荷とレイテンシは増え続けます。

リクエストごとの最大回数に加えて、リトライによる追加トラフィックを最大10%程度に制限する全体バジェットも設定しましょう。最後のリトライ後も依存先が停止しているなら、それはリトライではなくサーキットブレーカーで処理すべき状態です。

CORSエラーの解決方法: Access-Control-Allow-Originのデバッグ

Akira — Mon, 31 Aug 2026 10:47:18 +0000

新しいフロントエンドをリリースしてコンソールを開くと、赤いCORSエラーが表示され、リクエストが「CORSポリシーによってブロックされた」と告げられることがあります。ApidogやcurlではAPIが正常に動作するのに、ブラウザはJavaScriptへ応答を渡してくれません。しかし、原因と修正箇所を理解すれば、CORSは謎ではありません。

今すぐApidogを試す

CORSエラーはブラウザによって強制されますが、原因の多くはサーバー設定にあります。サーバーが正しいAccess-Control-Allow-Originヘッダーを返さないため、ブラウザが応答をJavaScriptから隠します。したがって、修正箇所は通常フロントエンドではなくサーバーです。

この記事では、CORSの仕組み、プリフライトリクエスト、代表的な6つのエラーと修正方法、Express・Spring Boot・Nginxの設定例、ブラウザ外でのデバッグ方法を紹介します。

CORSエラーとは何か

CORSはCross-Origin Resource Sharing（クロスオリジンリソース共有）の略です。ブラウザはデフォルトで同一オリジンポリシーを適用します。

たとえば、https://app.example.comで動作するJavaScriptは、スキーム、ホスト、またはポートが異なるhttps://api.example.comの応答を読み取れません。CORSは、サーバーが明示的にこの制限を緩和するための仕組みです。詳しくは、MDNのCORSドキュメントとFetch仕様を参照してください。

押さえるべきポイントは3つです。

強制するのはブラウザ: サーバー間通信、curl、デスクトップAPIクライアントはCORSチェックを行いません。
設定するのはサーバー: ブラウザはサーバーのレスポンスヘッダーを見て、応答を公開してよいか判断します。
リクエスト自体は到達することがある: 単純なリクエストでは、サーバーが処理して応答を返した後、ブラウザがその応答をJavaScriptから隠します。

CORSはAPIを外部から遮断するファイアウォールではありません。Cookieを使ってクロスオリジンデータを読み取ろうとする悪意のあるページからユーザーを守るためのブラウザ側の制御です。

CORSエラーが出たら、フロントエンドで回避するのではなく、レスポンスに欠けている、または誤っているヘッダーをサーバーで修正しましょう。

プリフライトリクエストの構造

特定のクロスオリジンリクエストでは、ブラウザが本リクエストの前にOPTIONSリクエストを送信します。これは、次のような場合に発生します。

GET、HEAD、POST以外のメソッドを使う
Authorizationなどのカスタムヘッダーを送る
application/jsonなどのContent-Typeを使う

プリフライトの例です。

OPTIONS /v1/orders HTTP/1.1
Host: api.example.com
Origin: https://app.example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: authorization, content-type

ブラウザは「https://app.example.comのページが、指定したヘッダーでPOSTしてよいか」と確認しています。サーバーは次のように応答します。

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Max-Age: 86400
Vary: Origin

必要な情報が欠けていると、ブラウザは本リクエストを送信する前に処理を中止します。APIエンドポイントには到達せず、ログにはOPTIONSだけが残り、コンソールにはCORSエラーが表示されます。

Access-Control-Max-Ageはプリフライトの判定をキャッシュする時間を秒で指定します。上記の例では86400秒です。

CORSをデバッグするときは、まず「失敗したのはプリフライトか、本リクエストか」を切り分けてください。

よくある6つのCORSエラーと修正方法

1. `Access-Control-Allow-Origin`ヘッダーがありません

サーバーがCORSヘッダーをまったく返していないため、ブラウザが応答をブロックしています。

修正方法: 特定のオリジン、または認証情報を使わない公開APIの場合に限り*を返します。

Access-Control-Allow-Origin: https://app.example.com

エラー応答にもCORSヘッダーを付ける必要があります。たとえば、ミドルウェアが2xxレスポンスだけを処理していると、APIが500を返したときに本来のサーバーエラーではなくCORSエラーが表示されます。403 Forbiddenや500を含むすべてのレスポンスでヘッダーが付くことを確認してください。

2. ワイルドカード`*`と認証情報を併用しています

フロントエンドがcredentials: 'include'でCookieや認証情報を送っているのに、サーバーが次のように応答しているケースです。

Access-Control-Allow-Origin: *

認証情報付きリクエストで*を使うことはできません。この組み合わせを許可すると、任意のWebサイトが認証済みレスポンスを読み取れるためです。

修正方法: 正確なオリジンと認証情報の許可を返します。

Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Credentials: true

受信したOriginを許可リストと照合してから返してください。任意のオリジンをそのまま反射すると、CORSの保護が無効になります。

3. プリフライトがアクセス制御チェックに失敗します

サーバーがOPTIONSを処理していない可能性があります。POSTだけを定義しているため404または405になる場合や、プリフライトには認証情報が付かないため、認証ミドルウェアが401を返す場合があります。

修正方法: 認証より前にOPTIONSを処理し、CORSヘッダーを含む2xxレスポンスを返します。手動で設定する場合は次のようになります。

app.options('/v1/orders', (req, res) => {
  res.set({
    'Access-Control-Allow-Origin': 'https://app.example.com',
    'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
    'Access-Control-Allow-Headers': 'Authorization, Content-Type'
  });
  res.sendStatus(204);
});

多くのフレームワークでは、CORSミドルウェアを最初にマウントするだけで解決できます。

4. ヘッダーのオリジンが一致しません

サーバーはAccess-Control-Allow-Originを返していますが、リクエストのOriginと異なっています。

よくある原因は次のとおりです。

http://localhost:5173からアクセスしているのに、本番オリジンを返している
httpとhttpsが一致していない
https://app.example.com/のように末尾スラッシュを付けている

修正方法: リクエストのOriginを許可リストと正確に比較し、一致した値を返します。また、キャッシュ対策としてVary: Originを追加します。

const allowed = ['https://app.example.com', 'http://localhost:5173'];
if (allowed.includes(req.headers.origin)) {
  res.set('Access-Control-Allow-Origin', req.headers.origin);
  res.set('Vary', 'Origin');
}

5. リクエストヘッダーまたはメソッドが許可されていません

代表的なメッセージは次の2つです。

authorizationがAccess-Control-Allow-Headersで許可されていない
PUTがAccess-Control-Allow-Methodsで許可されていない

プリフライト自体は成功していますが、レスポンスが本リクエストに必要なヘッダーやメソッドを許可していません。

修正方法: フロントエンドが実際に送るすべてのヘッダーとメソッドを追加します。

Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, X-Request-Id

ヘッダー名は大文字と小文字を区別しません。メソッドは大文字で指定します。

6. プリフライト中のリダイレクトは許可されません

プリフライトが301や302を返すURLに到達すると、ブラウザはリダイレクトに従わず処理を中止することがあります。

よくある原因は次のとおりです。

httpからhttpsへのリダイレクト
末尾スラッシュを補うルーターのリダイレクト
/v1/ordersから/v1/orders/へのゲートウェイリダイレクト

修正方法: フロントエンドを最終URLへ直接向けてください。最初からhttpsを使い、ルーターの末尾スラッシュ規則に合わせます。手動のOPTIONSリクエストで、エンドポイントが3xxではなく2xxを返すことも確認してください。

サーバー設定例

Express

ヘッダーを手動で設定する代わりに、公式のcorsミドルウェアを使用します。

const express = require('express');
const cors = require('cors');
const app = express();

app.use(cors({
  origin: ['https://app.example.com', 'http://localhost:5173'],
  methods: ['GET', 'POST', 'PUT', 'DELETE'],
  allowedHeaders: ['Authorization', 'Content-Type'],
  credentials: true,
  maxAge: 86400
}));

認証ミドルウェアより前にマウントしてください。これにより、プリフライトが認証トークン不足で拒否されるのを防げます。

Pythonの場合は、Flask-CORS拡張機能で同じヘッダーロジックを適用できます。

Spring Boot

WebMvcConfigurerでグローバル設定を行います。

@Configuration
public class CorsConfig implements WebMvcConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/v1/**")
            .allowedOrigins("https://app.example.com")
            .allowedMethods("GET", "POST", "PUT", "DELETE")
            .allowedHeaders("Authorization", "Content-Type")
            .allowCredentials(true)
            .maxAge(86400);
    }
}

Spring Securityを使う場合は、セキュリティフィルターチェーンでも.cors(Customizer.withDefaults())を呼び出してください。そうしないと、MVC設定に到達する前にセキュリティ層がプリフライトをブロックします。詳細はSpringのCORSドキュメントを参照してください。

Nginx

Nginxでアプリの前段処理を行う場合は、エッジでプリフライトに応答できます。

location /v1/ {
    if ($request_method = OPTIONS) {
        add_header Access-Control-Allow-Origin "https://app.example.com" always;
        add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
        add_header Access-Control-Allow-Headers "Authorization, Content-Type" always;
        add_header Access-Control-Max-Age 86400 always;
        return 204;
    }
    add_header Access-Control-Allow-Origin "https://app.example.com" always;
    add_header Vary "Origin" always;
    proxy_pass http://backend;
}

alwaysは重要です。これがないと、Nginxは4xxや5xxレスポンスでadd_headerを適用しません。その結果、失敗したリクエストでCORSエラーが元のサーバーエラーを隠します。

また、CORSを担当するレイヤーは1つに決めてください。Nginxとアプリケーションの両方がヘッダーを追加すると、Access-Control-Allow-Origin: *, *のような重複が発生し、ブラウザに拒否されます。

Apidogでブラウザ外からCORSをデバッグする

コンソールエラーはブラウザがブロックした事実を示しますが、サーバーが実際に返した内容までは分かりません。ブラウザを経由せずに同じリクエストを送ると、問題をすばやく切り分けられます。

ApidogはデスクトップAPIクライアントのため、ブラウザのCORSチェックを受けません。フロントエンドと同じリクエストを送信し、次のように判断できます。

Apidogでは成功する: APIロジックは正常で、CORSヘッダーの問題である可能性が高い
Apidogでも失敗する: CORSではなく通常のAPIバグ。一般的なAPIテスト手法で調査する

1. 本リクエストを再現する

ブラウザのネットワークタブから失敗したリクエストをコピーし、同じメソッド、ヘッダー、ボディでApidogから送信します。ステータスとレスポンスボディを確認してください。ここで500が返るなら、CORSは根本原因ではありません。

2. プリフライトを手動で送信する

新しいリクエストを作成し、メソッドをOPTIONSに設定します。次のヘッダーを追加してください。

Origin: https://app.example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: authorization, content-type

3. レスポンスヘッダーを確認する

次のヘッダーを探し、フロントエンドが必要とする値と比較します。

Access-Control-Allow-Origin
Access-Control-Allow-Methods
Access-Control-Allow-Headers

ヘッダーの欠落、誤ったオリジン、3xxステータスは、コンソールで推測しなくても特定できます。

4. 修正を検証する

サーバー設定を変更したら、保存済みのOPTIONSリクエストを再送信し、ヘッダーが更新されたことを確認します。フロントエンドの再デプロイやキャッシュクリアは不要です。

この手順なら、「APIクライアントでは動くのにブラウザでは失敗する」という問題を数秒で切り分けられます。PostmanのCORSテストも本質は同じです。デスクトップクライアントはCORSをスキップし、ブラウザはサーバーのCORSヘッダーを検証します。

Apidogを無料でダウンロードし、通常のエンドポイントテストと一緒にOPTIONSリクエストを保存しておけば、次回のCORS問題もすぐに確認できます。

30秒で確認するCORSチェックリスト

バグを報告する前に、次を確認してください。

失敗したレスポンスにAccess-Control-Allow-Originが含まれているか
値がページのオリジン（スキーム、ホスト、ポート、末尾スラッシュなし）と完全に一致しているか
Cookieや認証情報を使う場合、特定のオリジンとAccess-Control-Allow-Credentials: trueを返しているか
OPTIONSが、必要なメソッドとヘッダーを含む2xxを返しているか
プリフライトURLがリダイレクトしていないか
401、403、500などのエラー応答にも成功応答と同じCORSヘッダーがあるか

10回中9回は、この6項目のいずれかに原因があります。Apidogで手動のOPTIONSリクエストを送り、サーバー設定を修正しましょう。

よくある質問

なぜブラウザでのみCORSエラーが発生するのですか？

CORSを強制するのはブラウザだけだからです。同一オリジンポリシーにより、ブラウザはクロスオリジンレスポンスのAccess-Control-Allow-Originを検証します。

curl、バックエンドサービス、デスクトップクライアントにはこの制約がありません。ブラウザ以外では成功する場合、API自体は正常で、サーバーのCORSヘッダーが欠落または誤設定されている可能性が高いです。

CORSはPostmanやApidogにも適用されますか？

いいえ。PostmanやApidogはブラウザのサンドボックス内で動作しないデスクトップアプリケーションなので、CORSをバイパスします。これにより、ブラウザのフィルタリングなしでサーバーの生のレスポンスヘッダーを確認できます。

PostmanのCORSテストで混乱しやすいのはこの点です。デスクトップクライアントで成功してもブラウザで動く証明にはなりませんが、失敗しているレイヤーの特定には役立ちます。

CORSエラーはセキュリティ機能ですか、それともバグですか？

セキュリティ機能です。ブラウザが、サーバーの許可なしにクロスオリジンのレスポンスデータをスクリプトへ公開していないことを示します。

ブラウザのフラグや拡張機能でCORSを無効にしても、自分の環境で症状を隠せるだけです。他のユーザーには問題が残るため、サーバーのヘッダーを修正してください。

`Access-Control-Allow-Origin: *`はどこでも使えますか？

Cookieや認証情報を使わない公開読み取り専用APIでのみ使用できます。

認証情報付きリクエストではワイルドカードは拒否されます。認証が必要なAPIでは、オリジンの許可リストを保持し、一致したオリジンを返し、共有キャッシュがレスポンスを分離できるようVary: Originも送信してください。

ApidogとGHE.comリポジトリの連携方法

Akira — Mon, 31 Aug 2026 10:26:34 +0000

Apidogは、専用の*.ghe.comドメインでホストされたGitHub Enterprise Cloudデータレジデンシーテナントに接続できます。組織管理者がテナントとOAuthアプリを設定すると、許可されたプロジェクトユーザーはリポジトリを接続し、OpenAPIのインポート、バックアップ、同期ワークフローを利用できます。

今すぐApidogを試す

この統合は、GitHub Enterprise CloudデータレジデンシーSaaSテナント専用です。GitHub Enterprise ServerやカスタムGitHubドメインはサポートしていません。

始める前に

以下を準備します。

統合機能を利用できるApidog Enterprise組織
Apidogの組織管理者権限
https://company.ghe.comのようなルート*.ghe.comドメイン上のGitHub Enterprise Cloudデータレジデンシーテナント
テナントでOAuthアプリを作成する権限
接続対象のGitHub組織、リポジトリ、ブランチへのアクセス権

リポジトリを接続するユーザーには、ApidogでプロジェクトレベルのGit接続権限も必要です。

ステップ1：GHE.comテナントでOAuthアプリを作成する

組織のGHE.comテナントにサインインします。
OAuthアプリ設定を開き、新しいOAuthアプリを作成します。
識別可能なアプリケーション名を入力します。
ホームページURLをhttps://apidog.comに設定します。
認証コールバックURLをhttps://api.apidog.com/passport/github/callbackに設定します。
OAuthアプリを登録します。
Client IDをコピーします。
Client Secretを生成し、安全な場所にコピーします。

コールバックURLは、Apidogのドキュメントに記載されているURLと完全に一致している必要があります。

Client Secretは、承認済みの秘密管理システムに保存してください。スクリーンショット、チケット、共有ドキュメントには記載しないでください。

ステップ2：ApidogでGHE.comテナントを設定する

この統合を設定または解除できるのは組織管理者だけです。

Apidog組織を開きます。
組織設定に移動します。
GitHub統合を開きます。
GitHub Enterprise Cloud Data Residencyを見つけ、設定を選択します。

GHE.comホストURLを入力します（例：https://company.ghe.com）。
認証方法としてOAuth Appを選択します。
OAuthアプリのClient IDを入力します。
OAuthアプリのClient Secretを入力します。
設定を保存します。

テナントホストとOAuthアプリの認証情報は、組織レベルで設定します。

保存後、Apidogは設定済みのホストURLを表示します。Client Secretが再表示されたり、事前入力されたりすることはありません。

設定を編集するときにClient Secretフィールドを空のままにすると、既存のシークレットが保持されます。新しい値を入力するのは、シークレットをローテーションする場合だけです。

ステップ3：Apidogプロジェクトからリポジトリを接続する

組織レベルの設定が完了したら、次の手順で接続します。

対象のApidogプロジェクトを開きます。
Git接続またはGitインポートワークフローを開始します。
GitHub Enterprise Cloudを選択します。
設定済みのGHE.comテナントの認証ページに進みます。
サインインしてOAuthアプリを承認します。
GitHub組織を選択します。
リポジトリとブランチを選択します。
接続を完了します。

認証は標準のgithub.comではなく、設定済みのGHE.comテナントで実行されます。

組織またはリポジトリが表示されない場合は、Apidogの組織設定を変更する前に、GitHubアカウントのアクセス権とOAuthアプリの認証状態を確認してください。

ステップ4：OpenAPIファイルをインポートする

接続済みのリポジトリからOpenAPIまたはSwaggerファイルをインポートします。

Apidogプロジェクトでインポートワークフローを開始します。
OpenAPI/Swaggerを選択します。
Gitリポジトリを選択します。
GitHub組織、リポジトリ、ブランチ、ファイルを選択します。
続行を選択します。
既存のターゲットモジュールを選択するか、新しいモジュールを作成します。
インポートを完了します。
結果を承認する前に、インポートされたエンドポイントとスキーマを確認します。

プロジェクトに必要なリポジトリ、ブランチ、仕様ファイルを選択します。

初回インポートでは、特にターゲットモジュールに既存のAPI定義がある場合、非本番プロジェクトを使用してください。

ステップ5：継続的な同期ワークフローを選択する

リポジトリ接続では、次のワークフローを利用できます。チーム内で信頼できる情報源（source of truth）を1つ決め、運用ルールを文書化してください。

ワークフロー	使用する状況	重要な動作
手動インポート	必要なときだけ変更をApidogに取り込む	各インポートとターゲットモジュールを確認する
スケジュールされたインポート	Gitファイルをソースとして、Apidogを一定間隔で更新する	設定した実行モードに従い、ローカルクライアントまたはセルフホスト型Runnerで実行する
Gitへのバックアップ	Apidogのコンテンツをリポジトリファイルに書き込む	リポジトリ、ブランチ、ターゲットファイルパスを設定する。自動バックアップは夜間のランダムなオフピーク時間に実行される
Spec-firstモード	仕様ファイルを唯一の信頼できる情報源として、Git中心のワークフローで編集する	現在ベータ版。ウェブフックのインストールには通常、リポジトリ管理者権限が必要

明確な競合解決ルールがない状態で、同じファイルに相反する自動ワークフローを2つ設定しないでください。

Gitへのバックアップを設定する

プロジェクト設定でGit接続を作成または選択します。
モジュールの概要 > API仕様を開きます。
OpenAPI仕様を追加または選択します。
Gitリポジトリへのバックアップを有効にします。
リポジトリ接続、ブランチ、ターゲットファイルパスを選択します。
設定を保存します。

リポジトリを信頼できる情報源にする場合は、スケジュールされたインポートまたはSpec-firstモードを確認してください。

ステップ6：統合を確認する

小規模なエンドツーエンドテストを実行します。

認証ページが設定済みのGHE.comテナントで開くことを確認する
期待する組織とリポジトリだけが利用可能であることを確認する
既知のOpenAPIファイルをインポートし、結果をソースと比較する
使い捨てブランチで、選択したバックアップまたは同期の方向をテストする
ブランチ保護とリポジトリ権限が期待どおりに動作することを確認する
同期ログとエラーを確認する
OAuthアプリのClient Secretをローテーションし、文書化した更新プロセスが機能することを確認する

ウェブフック同期を使用する場合は、インストーラーがリポジトリ管理者権限を持ち、想定したプッシュイベントで同期が開始されることも確認してください。

組織設定の更新またはクリア

組織管理者は、ホストURLまたはClient IDを編集できます。Client Secretをローテーションする場合は、新しい値を入力します。

組織レベルの設定を削除するには、組織設定 > GitHub統合を開き、データレジデンシー統合を見つけて設定をクリアを選択します。

設定をクリアすると、統合を再設定するまでユーザーは新しいGitHub Enterprise Cloud接続を作成できません。既存の接続も、トークンの状態や組織設定によっては再設定または再認証が必要になる場合があります。

トラブルシューティング

問題	確認事項
統合オプションが利用できない	組織がEnterprise機能にアクセスでき、自分が組織管理者であることを確認する
OAuthがコールバックエラーを返す	OAuthアプリのコールバックが`https://api.apidog.com/passport/github/callback`と完全に一致していることを確認する
認証でgithub.comが開く	組織レベルのホストが意図したルート`*.ghe.com`テナントであることを確認する
リポジトリが見つからない	認証済みGitHubユーザーの組織・リポジトリへのアクセス権とOAuthの制限を確認する
プロジェクトユーザーが接続を作成できない	必要なプロジェクトレベルのGit接続権限を確認する
インポートまたは同期が失敗する	選択したブランチ、ファイルパス、ファイル形式、リポジトリ権限、同期ログを確認する

セキュリティとデータレジデンシーの境界

GHE.com統合を設定または解除できるのは組織管理者だけです。
Client Secretは設定後に表示されません。
プロジェクト権限によって、Git接続を作成または更新できるユーザーが制御されます。
OAuth認証は設定済みのGHE.comテナントを通じて実行されます。
OAuth権限には、組織、リポジトリ、ブランチの読み取り、ファイルのインポート、バックアップの書き込み、同期ワークフローで必要なリポジトリフックの管理に必要なアクセスが含まれる場合があります。

データレジデンシーテナントに接続しただけでは、GitHubまたはApidog関連のすべてのデータが単一リージョンに留まることは証明されません。GitHubは、レジデンシーサービスの対象データと関連する例外を文書化しています。Apidogは独自のストレージおよびデプロイメントモデルを持つ独立した接続サービスです。データレジデンシーまたはコンプライアンス評価では、両ベンダーの最新ドキュメントを確認してください。

Secret Scannerを活用した漏洩APIキーの検出と対処法

Akira — Mon, 31 Aug 2026 10:25:38 +0000

Apidog Secret Scannerで機密情報の漏洩を調査・対応する

Secret Scannerは、サポートされているApidogアセット内のAPIキー、アクセストークン、認証情報、Webhook URLなど、機密情報の可能性がある値を検出します。検出結果には出現場所が表示されますが、完全な値は表示されません。

今すぐApidogを試す

この記事では、検出結果の確認から実際の漏洩への対応、解決理由の記録、カスタム検出パターンの追加、チームアナリティクスの確認までを説明します。

始める前に

Secret ScannerはEnterprise SaaSプランで利用できます。現在、Apidogオンプレミスでは利用できません。

権限によって実行できる操作が異なります。

役割	利用可能なアクション
組織オーナーまたは管理者	チーム全体の組織レベルのレポートを表示
チームオーナーまたは管理者	検出結果の確認、解決・再オープン、カスタムパターンの管理、アナリティクスの表示
チームメンバーまたはゲスト	アクセス権を持つプロジェクトの検出結果を表示

テストには必ず架空の値を使用してください。実際の認証情報をリソースに貼り付ける必要はありません。

1. 組織レポートを確認する

組織オーナーと管理者は、組織レポートで未解決の検出結果があるチームを特定できます。

組織レベルのSecret Scannerレポートを開く。
未解決の検出結果と、公開された漏洩の数を確認する。
最終検出時刻とスキャンステータスを確認する。
影響を受けるチームを開くか、チームオーナーまたは管理者に連絡する。

組織レポートは、フォローアップが必要なチームの特定に役立ちます。

組織レポートはトリアージ用です。詳細な調査と解決は、影響を受けるチームのSecret Scannerページで行います。

2. 検出結果を開いてフィルターする

チーム内でSecret Scannerを開き、Secrets Detectedを選択します。

次のフィルターで一覧を絞り込みます。

ステータス
プロジェクト
パターン
リソースタイプ
キーワード

検出結果は、検出パターンと安全なフィンガープリントでグループ化されます。同じ値が複数の場所に存在する場合、1つの検出結果に複数の出現箇所が表示されます。

値はマスクされています。プロジェクト、リソースタイプ、出現回数、ソースの場所を使って調査します。

まず、公開漏洩としてマークされた未解決の検出結果を確認します。次に、複数のリソースまたはプロジェクトに出現する検出結果を調査します。

3. すべての出現箇所を調査する

検出結果を開き、各出現箇所で次の情報を確認します。

値を含むプロジェクトとリソース
リソースタイプとソースの場所
公開ドキュメントに表示されているか
最初と最後の検出時刻
実際の認証情報か、誤検知か

マスクされたスニペットだけで判断しないでください。ソースリソースを確認し、必要に応じてリソース所有者に発行システムを確認してもらいます。認証情報そのものをチケットやチャットにコピーするのは避けてください。

4. 実際の漏洩に対応する

Secret Scannerは漏洩の可能性を報告するだけで、認証情報を変更しません。確認されたシークレットは、発行元のシステムで対応します。

次の順序で作業してください。

外部サービスで認証情報を失効、ローテーション、または無効化する。
利用可能な使用ログを確認し、予期しないアクティビティを調査する。
Apidogに表示されているすべてのソース出現箇所から値を削除する。
ワークフローで必要な場合は、生の値を適切な変数またはVault Secret参照に置き換える。
変更した各リソースを保存し、非同期スキャンを再実行させる。

認証情報が公開ドキュメントに表示されていた場合、不審な利用が確認できなくても、外部に公開されたものとして扱います。

Apidogから値を削除しても、すでにコピーされた値は無効になりません。実際の漏洩に対する主要な封じ込め策は、ローテーションまたは失効です。

5. 解決理由を記録する

対応後、検出結果に解決理由を設定します。

解決理由	使用する状況
失効済み	実際のシークレットであり、Apidog以外で失効、ローテーション、または無効化した
誤検知	検出された値がシークレットではない
修正しない	実際のシークレットだが、チームがリスクを受け入れて変更しない

検出結果を解決済みにしても、Apidog上のステータスが変わるだけです。元の値が失効、ローテーション、無効化、削除、置換されるわけではありません。

追加対応が必要になった場合は、検出結果を再オープンしてください。

6. クリーンアップを確認する

Secret Scannerはリアルタイムではなく、非同期で実行されます。サポート対象のリソースが追加されたとき、または変更後に保存を選択したときにスキャンがトリガーされます。

修復後は、次の項目を確認します。

既知のすべてのソース出現箇所を変更した
影響を受けるリソースを保存した
非同期スキャンが完了する時間を確保した
検出結果と最終検出時刻を確認した
発行サービスで古い認証情報が使えなくなったことを別途確認した

スキャナーのステータスは、認証情報の有効性テストではありません。失効状態は外部サービスで確認してください。

7. カスタム検出パターンを追加する

チームオーナーとチーム管理者は、組織固有のシークレット形式に対応するカスタムパターンを作成できます。

Secret Scanner > Patternsを開く。
カスタムパターンの作成を選択する。
わかりやすい名前を入力する。
正規表現と有効なキーワードを追加する。
架空の値でテストする。
パターンを有効にして保存する。

現在の制限は次のとおりです。

チームごとに最大5つのカスタムパターン
パターン名は最大128文字
UIで指定する正規表現は最大256文字
キーワードは最大10個
各キーワードは最大64文字

組み込みパターンは読み取り専用です。内部の正規表現は表示されず、編集、削除、有効化、無効化はできません。

8. チームアナリティクスを確認する

チームオーナーと管理者は、Analyticsを開いて検出結果の集中箇所を確認できます。

アナリティクスを使って、追加レビューが必要なプロジェクト、パターン、アセットタイプを特定します。

アナリティクスは優先順位付けに役立ちますが、各検出結果はソースレベルで調査してください。

サポートされるアセットタイプ

Secret Scannerは、現在次のサポート対象アセットをスキャンします。

APIおよびAPIリクエスト
APIケース
プロジェクトモジュールおよびプロジェクトモジュール変数
レスポンス例
Markdownドキュメントおよびデータスキーマ
環境変数、グローバル変数、チーム変数
共通スクリプトおよび共通パラメータ

出現箇所で表示できるソースの詳細は、リソースタイプと閲覧者の権限によって異なります。

トラブルシューティング

問題	確認すべきこと
最近の変更が結果に反映されない	スキャンは非同期です。リソースが保存されていることを確認し、後で再確認します。
チームメンバーが検出結果を見られない	関連プロジェクトへのアクセス権を確認します。
パターンやアナリティクスを管理できない	チームオーナーまたはチーム管理者の権限が必要です。
解決済みの検出結果に機能するシークレットが残っている	解決ステータスは認証情報を変更しません。発行サービスで失効またはローテーションします。
外部リポジトリがスキャンされない	Secret Scannerは外部のGitHubまたはGitLabリポジトリをスキャンしません。リポジトリプロバイダーのスキャン機能も使用します。

重要な制限事項

Secret Scannerは、次のことを保証する機能ではありません。

ユーザーによるシークレット入力の防止
ドキュメント公開のブロック
外部リポジトリのスキャン
すべてのシークレット形式の検出
ソース値の自動削除
変数やVault参照への自動置換

最小権限での発行、安全な保管、ローテーション、失効、利用状況の監視を含む認証情報管理プロセスの一部として利用してください。

Apidogで監査ログを確認・エクスポートする方法

Akira — Mon, 31 Aug 2026 10:25:30 +0000

Apidog監査ログを調査・エクスポート・API収集する方法

Apidog監査ログは、組織レベルでサポートされるセキュリティおよび管理アクティビティを記録します。組織の所有者と管理者は、実行者、実行時刻、送信元IPアドレス、影響を受けた組織リソースを確認できます。

今すぐApidogを試す

このチュートリアルでは、監査ログのフィルタリング、調査、CSVエクスポート、APIベースの収集方法を説明します。監査ログは管理アクティビティの記録であり、本番APIリクエストやゲートウェイアクセスログではありません。

始める前に

監査ログはEnterprise SaaSプランで利用できます。
Apidogオンプレミス版では現在利用できません。
表示、エクスポート、APIクエリを実行できるのは、組織の所有者と組織管理者のみです。
データの保持期間は180日間です。

180日を超える調査が必要な場合は、レコードが期限切れになる前にエクスポートまたは収集してください。

1. 監査ログを開く

Apidog組織を開き、組織設定から監査ログへ移動します。

ログには次の情報が表示されます。

実行者
イベント
説明
IPアドレス
時刻

監査ログは、サポートされているセキュリティおよび管理イベントの組織レベルの記録です。

認証イベントは、Apidogがイベントを組織に確実に帰属できる場合にのみ表示されます。

2. 調査期間を定義する

まず、調査対象を具体的な質問に絞ります。

メンバーの組織ロールを変更したのは誰か
アクセストークンがローテーションまたは失効された日時
SSO設定を変更したアカウント
ドキュメントサイトや共有ドキュメントのアクセス設定を変更したユーザー
SCIM経由でプロビジョニングまたは削除されたユーザー

最も短く実用的な期間を選択してください。利用可能なプリセットは、過去7日、30日、90日、180日です。180日間の保持期間内でカスタム範囲も指定できます。

IDプロバイダー、チケット管理システム、Git、サービスログと照合する場合は、インシデント対応や監査で使用するタイムゾーンを先に記録しておきます。

3. フィルターを適用する

次の条件でログを絞り込みます。

期間：イベントが発生した可能性のある時間帯
イベント：ロール変更、サインイン失敗、アクセストークン変更、監査ログのエクスポートなど
実行者：アクションを実行したユーザーまたはインテグレーション

期間、イベント、実行者を組み合わせると、調査対象のレコードを効率よく分離できます。

実行者が分からない場合は、期間とイベントから始めます。イベント名が不明な場合は、実行者と短い期間を指定してください。

4. イベントの詳細を確認する

各レコードで、次の項目を確認します。

イベント時刻
実行者またはインテグレーション
アクションと説明
送信元IPアドレス
影響を受けたメンバー、チーム、設定、リソース

次に、イベントを追加の証拠と関連付けます。

質問	追加で確認する証拠
アクションは承認されていたか	変更リクエスト、アクセスレビュー、チケット
サインインは想定されたものか	IDプロバイダーのサインインログ、デバイスログ
その後にどのAPIトラフィックが発生したか	ゲートウェイ、アプリケーション、APIアクセスログ
どのコンテンツが変更されたか	リソース履歴、仕様の差分、Git履歴
資格情報が使用されたか	資格情報を発行したシステムのログ

監査イベントは、サポート対象のアクションが発生したことを示します。ただし、それだけでアクションが承認済み、安全、または準拠していることを証明するものではありません。

5. フィルター結果をCSVにエクスポートする

フィルターを適用した後、次の手順で保存します。

表示された結果セットを確認する
CSVエクスポートを選択する
承認済みの調査・監査用ストレージに保存する
エクスポート時刻、フィルター条件、ファイルを扱った担当者を記録する

CSVエクスポートでは、監査ログページに現在適用されているフィルターが使用され、180日間の保持期間内で条件に一致するレコードが含まれます。

監査ログのエクスポート自体も監査ログに記録されます。CSVは独立したコピーであるため、適切なアクセス制御、保持ポリシー、整合性管理で保護してください。

6. APIで監査ログを収集する

Enterprise組織では、監査ログAPIを使ってプログラムからレコードをクエリできます。APIは、180日間の保持期間内での時間ウィンドウ検索とカーソルページネーションに対応しています。

スケジュール収集を実装する場合は、次の点を設計に含めます。

保持期間より短い収集間隔を設定する
明確な開始時刻と終了時刻を指定する
結果セットが完了するまでカーソルを処理する
収集チェックポイントを保存する
サイレントギャップを作らず、失敗したウィンドウを再試行する
収集先の機密性と保持ポリシーに従ってデータを保護する

各APIクエリは、次の情報を含むサマリーとして記録されます。

呼び出し元
IPアドレス
クエリウィンドウ
制限
結果
タイムスタンプ

返却された完全なペイロードは、イベントメタデータにはコピーされません。

認証方式、エンドポイントパス、リクエストパラメータ、レスポンス解析を実装する前に、最新のAPIリファレンスを確認してください。検証していないコードサンプルを本番コレクターへそのままコピーしないでください。

調査記録を検証する

調査を終了する前に、次の項目を確認します。

使用した正確な期間とフィルターを保存した
関連するすべての結果ページを取得した
元のCSVまたはAPIレスポンスを承認済みの場所に保存した
重要なアクションをID、変更管理、ランタイムの証拠と関連付けた
保持期間、帰属、サポート対象外のイベントタイプによるギャップを記録した

アクセス変更を調査する場合は、現在の状態も確認してください。監査ログではロールが変更された事実を確認でき、メンバーページでは現在割り当てられているロールを確認できます。

機密データの取り扱い

Apidogは、監査ログページ、CSVエクスポート、APIレスポンスに同じ墨消しポリシーを適用します。監査レコードに次の情報は公開されません。

トークン値
パスワード
秘密値
未加工のSAMLアサーション
リセットトークン
秘密鍵
エクスポートされたファイルの内容

ただし、メタデータも機密情報になる可能性があります。エクスポートしたレコードへのアクセスを制限し、公開チケットや共有ドキュメントに配置しないでください。

トラブルシューティング

問題	確認事項
監査ログページを利用できない	組織がEnterprise SaaSを使用しており、閲覧者が組織の所有者または管理者であることを確認する
期待した認証イベントが見つからない	認証イベントは、Apidogが組織に確実に帰属できる場合のみ表示されるため、IDプロバイダーも確認する
CSVのレコード数が少ない	現在有効な期間、イベント、実行者のフィルターを確認する。エクスポートには現在のフィルターが使用される
APIコレクターがレコードをスキップする	クエリウィンドウ、カーソル処理、再試行、180日間の保持制限を確認する
ランタイムAPIコールが見つからない	ゲートウェイ、アプリケーション、APIアクセスログを確認する。Apidog監査ログは管理組織ログである

重要な制限事項

監査ログは、次の機能を提供しません。

本番リクエストログ
リソース履歴
ロールバック
完全なフィールドレベルのリカバリ

また、ネイティブSIEMコネクタ、Syslog、一般的なWebhook転送、リアルタイムストリーミングも現在サポートされていません。

スケジュールされたAPI収集は、レコードを外部の監視・監査パイプラインへ送信するための、現在文書化されている方法です。

Apidog 組織メンバーにチーム作成を許可する方法

Akira — Mon, 31 Aug 2026 10:25:00 +0000

既定では、組織メンバーはApidog組織内にチームを作成できません。組織オーナーまたは管理者は権限を有効にして、メンバーがホーム画面から組織所有のチームを作成できるようにできます。

Apidogを今すぐ試す

チームの作成者は新しいチームのチームオーナーになりますが、組織上の役割は引き続きメンバーです。チームを作成しても、組織管理ページへのアクセス権は付与されません。

はじめる前に

次のものを準備します。

組織オーナーまたは組織管理者のアクセス権
テスト用の組織メンバーアカウント
チーム名と所有権に関する命名・運用規約
必要に応じてバックアップオーナーになれる、アクティブな組織メンバー

この設定で変更されるのは、組織所有のチームを作成できるユーザーだけです。組織の役割、プロジェクト権限、既存チームの権限は変更されません。

ステップ1：組織メンバーによるチーム作成を有効にする

組織設定を開きます。
役割と権限に移動します。
組織メンバーがチームを作成できるオプションを有効にします。
設定を保存します。

この権限は既定で無効になっており、組織オーナーまたは管理者が変更できます。

組織オーナーと管理者は、この設定に関係なく組織チームを作成できます。

ステップ2：組織メンバーとしてチーム作成をテストする

テスト用の組織メンバーアカウントで、次の手順を実行します。

メンバーとしてサインインします。
Apidogホーム画面を開きます。
組織内に新しいチームを作成します。
チーム名を入力し、作成フローを完了します。
新しいチームを開きます。

次の項目を確認してください。

チームが組織に属している
作成したメンバーがチームオーナーになっている
作成者がチームオーナーの役割に従ってチームを管理できる
作成者が組織管理ページにはアクセスできない

最後の確認が重要です。チームオーナーはチームを管理できますが、組織管理者にはなりません。

ステップ3：チームとオーナーの状態を確認する

組織オーナーと管理者は、チーム管理ページで組織チームを監視できます。

組織のチーム管理ページを開きます。
各チームのチームオーナーを確認します。
非アクティブなどの理由で利用できないオーナーを確認します。
フォローアップが必要なチームを、オーナーや状態で検索またはフィルタリングします。

チームリストを使うと、オーナーが利用できず、所有権の移譲が必要なチームを特定できます。

定期的なアクセスレビューの際や、組織からメンバーを削除する前に、オーナーの状態を確認する運用がおすすめです。

ステップ4：チームの所有権を移譲する

組織オーナーと管理者は、1つまたは複数のチームを別の適格な組織メンバーに移譲できます。

組織のチーム管理ページを開きます。
新しいオーナーが必要なチームを選択します。
オーナーを変更を選択します。

複数のチームを選択し、同じ新しいオーナーに割り当てることもできます。

新しいチームオーナーを選択します。
移譲を確認します。

新しいオーナーは、組織の適格なアクティブメンバーである必要があります。

新しいオーナーには、次の条件があります。

利用可能なApidogアカウントを持っている
アクティブな組織メンバーである
組織がSAML SSOを使用している場合、組織に関連付けられたSSO IDを持っている

保留中、削除済み、無効、またはSSOとの関連付けが不完全なユーザーは選択できません。

所有権移譲後の変更点

移譲後は、次のようになります。

選択したメンバーがチームオーナーになる
必要に応じて、Apidogが新しいオーナーをチームに追加する
以前のオーナーがチームに残っている場合、その役割はチーム管理者になる
移譲が組織の監査ログに記録される

所有権の移譲で変更されるのはチームオーナーだけです。チームが別の組織に移動することはありません。

設定を確認する

すべてのメンバーに権限を付与する前に、次のチェックを実行します。

確認事項	期待される結果
メンバーがチームを作成する	チームが組織の下に作成される
作成者のチーム上の役割	作成者がチームオーナーになる
作成者の組織上の役割	作成者は組織メンバーのままである
組織設定へのアクセス	作成者は組織管理ページを開けない
オーナーの確認	組織オーナーまたは管理者がチームとオーナーの状態を確認できる
所有権の移譲	適格な新しいオーナーが所有権を受け取り、イベントが監査ログに表示される

パイロット運用の後、この権限を使うメンバーに、チーム名、オーナー、プロジェクト作成に関する規約を共有してください。

トラブルシューティング

問題	確認事項
メンバーがチームを作成できない	設定が有効であり、ユーザーが対象組織のアクティブなメンバーであることを確認します。
メンバーが組織設定へのアクセスを期待している	チームの所有権は、組織管理者権限を付与しません。
新しいオーナーを選択できない	アカウントがアクティブであり、SAML組織では組織のSSO IDにリンクされていることを確認します。
以前のオーナーが引き続きチームにアクセスできる	以前のオーナーがチームに残っている場合、役割はチーム管理者に変更されます。アクセスが引き続き必要か確認します。
チームが別の組織に移動した	所有権の移譲ではチームは移動しません。別のチーム移譲アクションが実行されていないか確認します。

重要な制限事項

この設定は、メンバーによる組織所有チームの作成を許可しますが、組織の管理権限は付与しません。
作成者には組み込みのチームオーナー役割が付与されます。チーム役割のカスタム権限は現在サポートされていません。
チームレベルの所有権だけで、すべてのプロジェクトの役割が決まるわけではありません。プロジェクトへのアクセスは別途確認してください。
所有権の移譲によって、組織間でチームが移譲されることはありません。

APIガバナンス：フレームワーク、統制、ベストプラクティスとツール

Akira — Mon, 31 Aug 2026 08:41:30 +0000

APIガバナンスの実践ガイド：APIポートフォリオを安全にスケールする方法

APIポートフォリオは、組織が一貫性を維持する能力よりも速く成長します。チームごとに命名モデルが異なる、所有者が不明確になる、共有例に認証情報が含まれる、異動後もアクセス権が残る、ドキュメントが実装に追いつかない、といった問題が起こりがちです。

今すぐApidogを試す

APIガバナンスは、すべてのAPI変更を委員会の承認に変えることなく、こうした問題を防ぐ再現可能な仕組みを提供します。

APIガバナンスとは、APIのライフサイクル全体を導くための意思決定権限、標準、ポリシー、プロセス、証拠の体系です。何を良しとするか、誰が責任を持つか、どのレイヤーで制御するか、適合性をどう検証するか、例外をどう扱うかを定義します。

効果的なガバナンスは設計ルールの一覧ではありません。API設計、ドキュメント、テスト、所有権、ID、アクセス権、認証情報保護、監査証拠、変更管理をつなぎ、チームが信頼性の高いAPIを速く構築できる「舗装された道」を作ります。

APIガバナンスの基本

実用的なガバナンスプログラムは、次の4つの問いに答えます。

何が求められるか APIまたはリスク階層ごとに、最低限の標準とポリシーを定義する。
誰が決定するか オーナー、レビュー担当者、エスカレーション先を割り当てる。
適合性をどう検証するか レビュー、チェックリスト、プラットフォーム制御、テスト、自動チェックを使う。
ルールに従えない場合はどうするか 例外、オーナー、補償的制御、有効期限、承認を記録する。

ポリシー、標準、制御、証拠の違い

概念	目的	例
ポリシー	求める結果を示す	本番用の認証情報を、共有API定義に平文で保存してはならない
標準	承認された作業方法を定義する	公開REST APIは、命名、エラー、バージョン管理、ページネーションの規則に従う
制御	逸脱を防止・検出・記録する	平文シークレットをブロックする、またはスキャナーでトークンを検出する
証拠	制御が機能したことを示す	チェック結果、承認記録、アクセスレビュー、テストレポート、監査イベント

この4要素は分離して管理するのではなく、接続して運用します。制御のないポリシーは適用できず、所有者のない制御は未解決の発見事項を生み、要件のない証拠はリスクが適切に処理されたことを証明できません。

APIガバナンス、API管理、APIセキュリティの違い

3つの領域は重なりますが、解決する問題は異なります。

分野	主要な問い	典型的な範囲
APIガバナンス	APIポートフォリオ全体に、どのルール、所有権、証拠を適用するか	意思決定権限、標準、ライフサイクル制御、例外、アクセスガバナンス、証拠
API管理	APIをどのように公開、運用、監視、提供するか	ゲートウェイ、ルーティング、レート制限、開発者ポータル、ランタイム分析、サブスクリプション
APIセキュリティ	API、認証情報、データ、コンシューマをどう保護するか	認証、認可、脅威対策、シークレット、テスト、監視、インシデント対応

ガバナンスは、API管理やAPIセキュリティの機能に対する期待値を設定します。たとえば、外部公開APIに次の要件を課せます。

責任あるオーナーがいる
承認済みの認証方式を使用する
非推奨化ポリシーを文書化する
ランタイムログを取得する

一方、APIゲートウェイ、IDシステム、開発プラットフォーム、可観測性基盤は、それぞれ異なる制御を実装します。

設計・コラボレーションプラットフォームは仕様、ドキュメント、ワークスペースアクセス、管理操作を扱い、ゲートウェイやセキュリティプラットフォームはランタイムトラフィックを扱います。通常、エンタープライズでは1つの製品ですべてを置き換えるのではなく、各レイヤーを連携させます。

エンタープライズでAPIガバナンスが必要な理由

小規模チームは、しばらく非公式な合意で運用できます。しかし、チーム、API、リポジトリ、環境、外部コンシューマが増えると、その方法は破綻します。

APIガバナンスを導入すると、次の効果が得られます。

不整合と手戻りを減らす 共通の設計・ドキュメント標準により、APIの予測可能性を高める。
所有権を可視化する API、ポリシー、例外、ライフサイクルの決定ごとに責任者を明確にする。
開発者セルフサービスを拡大する テンプレート、例、再利用可能なコンポーネント、明確なエスカレーションパスを提供する。
コラボレーション環境を保護する IDライフサイクル、RBAC、認証情報の扱い、管理証拠を整備する。
発見可能性と再利用性を高める APIカタログで既存機能を見つけ、重複実装を避ける。
変更を意図的に管理する バージョン、互換性、非推奨化、廃止のルールを定める。
監査に使える証拠を残す 制御結果、承認、監査イベント、修正記録を追跡可能にする。

目標は、均一性のための均一性ではありません。再現すべき決定は標準化しつつ、プロダクトチームがドメイン固有の選択をできる余地を残します。

APIの発見と再利用には、APIカタログも活用できます。

集中型とフェデレーテッド型の比較

集中型モデルでは、一貫したルールを定義できます。ただし、すべてのAPI変更を中央チームが承認するとボトルネックになります。

完全な分散型モデルは自律性を高めますが、標準の不一致やリスク管理のばらつきを招きます。そのため、大規模組織では通常、フェデレーテッドモデルが適しています。

中央のプラットフォームまたはイネーブルメントチームが、企業標準、テンプレート、共通制御、レポートを所有する。
ドメインチームが自身のAPIを所有し、必要に応じて追加標準を定める。
APIスチュワードが、ルールの解釈や日常的な質問を支援する。
例外プロセスで、正当な逸脱を期限付きで管理する。
高リスクAPIには、低リスクの内部APIより厳格なレビューを適用する。

フェデレーションは、承認権限を分散するだけではありません。委譲した決定にも、明確なオーナー、承認済みの制御セット、組織全体で確認できる証拠が必要です。

ライフサイクル状態や所有権の管理については、APIライフサイクルガバナンスも参照してください。

APIガバナンスの中核となる制御ドメイン

エンタープライズフレームワークは、スタイルルールだけでなく、APIのフルライフサイクルを対象にします。

ガバナンスドメイン	確認する問い	代表的な制御・証拠
運用モデルと所有権	API、標準、例外、レビューを誰が所有するか	RACI、サービスオーナー、スチュワード、エスカレーションパス
ポートフォリオとライフサイクル	どのAPIが存在し、誰が使い、どの段階にあるか	インベントリ、分類、状態、レビュー日、非推奨記録
設計と契約	インターフェースが一貫し、理解しやすく、互換性があるか	OpenAPI契約、命名・エラー標準、再利用スキーマ、互換性レビュー
ドキュメントと発見	コンシューマがAPIを理解し、見つけられるか	必須説明、例、制約、レスポンス定義、公開ドキュメント
テストとリリース	リリース前にAPIを検証したか	契約テスト、機能テスト、モック、結果、リリース基準、承認・例外
IDとアクセス	誰が参加、閲覧、変更、管理、エクスポートできるか	SSO、プロビジョニング、プロビジョニング解除、RBAC、グループマッピング、アクセスレビュー
認証情報と機密データ	シークレットをどう保存、参照、検出、修正するか	Vault参照、認証情報ポリシー、シークレットスキャン、ローテーション、所有権
監査と証拠	重要な管理操作を再構築できるか	管理監査ログ、エクスポート、APIクエリ、レビュー記録、証拠保持
ソース管理とデータ要件	仕様をどこに保存し、どの場所要件を適用するか	承認済みリポジトリ、ブランチ制御、権限、統合レビュー、データレジデンシー評価

これらを、制御目標、スコープ、オーナー、実装方法、証拠、レビュー頻度、例外手順、リスク階層を含む制御マトリックスに変換します。

APIガバナンスフレームワークの構築手順

1. ビジネスとリスクの成果から始める

最初から何百ものルールを作らないでください。まず、次のような成果を少数選びます。

予測可能なパートナーAPI
破壊的変更の削減
オンボーディングの高速化
認証情報の適切な管理
証明可能なオフボーディング

各要件を、消費者、リスク、運用上のメリットに結び付けます。どの成果にもつながらないルールは、不要なプロセスかもしれません。

2. APIインベントリを作り、リスク階層を割り当てる

次の情報を記録します。

APIとオーナー
コンシューマ
公開範囲
データの機密性
ライフサイクル状態
信頼できる情報源

インベントリが不完全だと、制御を一貫して適用できません。

APIを同じ基準で扱うのではなく、リスク階層を使い分けます。たとえば、公開された決済APIには、正式な互換性レビュー、より強力な証拠、短い修正期限が必要です。一方、一時的な内部プロトタイプには小さなベースラインを適用できます。

階層化の基準は、異なるチームが同様の判断に到達できる程度に明確にします。インベントリは、初回評価だけでなく、ライフサイクル管理とAPI発見にも接続してください。

3. 意思決定権限を割り当てる

少なくとも、次の責任者を定義します。

エンタープライズ標準
ドメイン固有の拡張
各APIとドキュメント
セキュリティ・プライバシーレビュー
例外承認
制御失敗の修正
非推奨化・廃止の決定

所有権は個人名だけでなく、役割やチームにも紐付けます。異動や退職があっても、運用を継続しやすくなります。

4. 最小限実行可能な制御セットを定義する

最初は、頻出する重大な問題に集中します。ベースラインには、次の項目を含めるとよいでしょう。

指定オーナーとライフサイクル状態
承認済み仕様形式によるAPI契約
命名、エラー、認証、バージョン管理、ページネーション
説明、例、パラメータ制約、レスポンス、エラーケース
必須テストとレビュー基準
平文シークレットではなく、承認済みの認証情報参照
RBACとオフボーディング手順
破壊的変更と非推奨化の手順
証拠と例外の記録

設計ベースラインにはAPI標準化を、ドキュメント要件にはAPIエンドポイントドキュメントチェックリストを利用できます。

5. デリバリーワークフローに制御を組み込む

チームが普段使うワークフロー内でチェックを実行すると、ガバナンスを継続しやすくなります。

ライフサイクル段階	ガバナンス活動
発見と計画	カタログを検索し、オーナーを特定し、リスクとデータを分類し、既存APIの再利用可能性を確認する
設計	契約を作成し、標準を適用し、ドキュメントの完全性と互換性制約を確認する
開発とテスト	モックとテストを使い、共有定義から認証情報を除外し、必要に応じて承認済みアーティファクトをソース管理と同期する
レビューとリリース	必須制御を評価し、証拠を記録し、発見事項を修正し、期限付き例外を承認する
運用と変更	アクセスをレビューし、認証情報をローテーションし、ランタイム証拠を収集し、バージョンを管理する
非推奨化と廃止	コンシューマへ通知し、移行を追跡し、アクセスと認証情報を削除し、証拠をアーカイブし、カタログを更新する

CI/CDやポリシーシステムで自動化できる制御もあります。プロダクトオーナー、アーキテクト、セキュリティ担当者による状況判断が必要な制御もあります。

自動化するのは説明責任ではなく、反復可能なチェックです。

6. 現実的な例外プロセスを作る

正当な理由により、標準に従えないケースは発生します。例外には以下を記録します。

対象APIと要件
標準を満たせない理由
リスクと補償的制御
オーナーと承認者
有効期限またはレビュー日
修正または承認の判断

例外を追跡すれば、「一時的な回避策」が見えない恒久ポリシーになることを防げます。

7. 舗装された道を提供する

要件だけでなく、次の再利用可能なリソースも提供します。

承認済みの例
テンプレート
スキーマコンポーネント
認証パターン
エラーモデル
チェックリスト
トラブルシューティングガイド

各制御が必要な理由と、準拠した実装例を示してください。これにより、ガバナンスは承認ゲートからイネーブルメントシステムへ変わります。

8. 成果を測定し、ベースラインを改善する

メトリクス、例外、インシデント、サポートへの問い合わせ、開発者フィードバックを定期的に確認します。

成果につながらないルールは廃止し、混乱を招くルールは明確化し、同じ失敗が続く場合は制御を強化します。

APIガバナンスのベストプラクティス

ライフサイクル全体に適用する

設計レビューだけでは、古いアクセス、未管理の認証情報、文書化されていない破壊的変更、廃止漏れには対応できません。発見から非推奨化まで、各段階に適切な制御を配置します。

リスクベースで制御する

全APIに共通する最低限のベースラインを定め、その上で次の要素に応じて制御を追加します。

公開範囲
データ感度
コンシューマへの影響
規制要件
ビジネス上の重要性

すべてのAPIに最も厳格な手続きを適用するより、リスクベースの方が説明しやすく、運用負担も小さくなります。

業界別の質問を追加する場合は、フィンテックAPIガバナンスチェックリストを参考にできます。ただし、外部チェックリストを自社のコンプライアンス評価そのものとみなしてはいけません。

ワークスペース制御とランタイム制御を分離する

次の制御は同じものではありません。

管理監査ログとAPIリクエストログ
ワークスペースRBACとランタイム認証
設計コンプライアンスチェックと本番環境での継続的な適用

各制御がどのレイヤーを対象とするかを明記し、他のレイヤーを担当するゲートウェイ、ID、セキュリティ、可観測性システムと連携します。

予防、検出、修正の順で考える

可能な場合は、次の方法で危険な操作を事前に防ぎます。

承認済みテンプレート
最小権限ロール
Vault参照
ブロックポリシー

予防で漏れた問題は、チェックやスキャナーで検出します。すべての発見事項に、オーナー、重要度、修正措置、目標日を設定してください。

標準をバージョン管理された製品として扱う

標準には、次の情報を含めます。

変更履歴
準拠例
移行ガイダンス
適用開始日

既存APIが新しいルールにどう対応すべきかを説明せずに、標準だけを変更しないでください。

例外をガバナンスデータとして分析する

例外をルール、チーム、根本原因別に集計します。類似した例外が多い場合、次の問題を示している可能性があります。

イネーブルメント不足
設計の悪い標準
製品の制限
自動化すべき制御の未自動化

開発者をフィードバックループに含める

チェックにかかる時間、チームがブロックされる場所、適用しにくいガイダンスを測定します。ガバナンスは、制御結果とデリバリー品質の両方を改善して初めて成功です。

APIガバナンスの測定方法

ポリシー数やレビュー完了数だけで成功を判断しないでください。カバレッジ、適合性、リスク、フロー、成果をバランスよく測定します。

メトリクス	計算例・解釈
所有権カバレッジ	説明責任のあるオーナーを持つAPI ÷ インベントリ内のAPI
ライフサイクルカバレッジ	現在の状態とレビュー日を持つAPI ÷ インベントリ内のAPI
設計適合性	必須設計制御に合格したAPI ÷ チェック済みAPI。リスク階層別に分類
ドキュメント完全性	ドキュメントベースラインを満たすエンドポイント ÷ 評価済みエンドポイント
例外の健全性	未解決例外を年齢、リスク、オーナー、有効期限別に表示
アクセス削除の遅延	オフボーディングから関連アクセス削除までの時間
認証情報発見の修正時間	露出の可能性がある認証情報を検出してから解決するまでの時間
破壊的変更率	計画外の破壊的変更を含むリリース ÷ 評価済みリリース
廃止の有効性	スケジュールどおりに廃止され、コンシューマが移行できたAPIの割合
開発者エクスペリエンス	制御通過までの時間、再失敗率、サポート量、チームのフィードバック

必ず分母とスコープを定義してください。ポートフォリオの一部だけを自己選択して測定した「合格率95%」には、ほとんど意味がありません。

ApidogがエンタープライズAPIガバナンスを支援する方法

Apidogは、API設計、ドキュメント、テスト、コラボレーション、エンタープライズワークスペースの制御を1つのAPI開発プラットフォームに統合します。

特に設計時とコラボレーションのガバナンスに強みがあります。一方、ランタイムゲートウェイ、インフラストラクチャ、SIEM、可観測性の制御とは、必要に応じて連携して使用します。

ガバナンス目標	関連機能	適用範囲
一貫したAPI設計	デザインファーストのワークフロー、OpenAPI、再利用可能な定義、エンドポイントコンプライアンスチェック	ユーザーが実行したチェックで、命名、ドキュメント、レスポンス構造を評価する。普遍的な継続適用として扱わない
完全なドキュメント	生成・共有ドキュメント、APIドキュメント完全性チェック	定義、説明、制約、レスポンス構造、ステータスコード、エラーなどを評価する
管理されたワークスペースID	SAML SSO、SCIMプロビジョニング、APIチーム向けRBAC、SAMLグループマッピング	Apidogの組織、チーム、プロジェクト、APIアセットへのアクセスを管理する。本番APIを呼び出す認可ではない。SCIMの操作範囲は、最新の公開ドキュメントを確認する
より安全な認証情報管理	環境・シークレット管理、Vault統合、エンタープライズポリシー、シークレットスキャナー	スキャナーは非同期で実行され、対応アセット内の露出の可能性があるシークレットを検出する。自動失効、ローテーション、削除、置換は行わない。修正にはAPIキーローテーションプロセスを使う
管理上の証拠	フィルター、CSVエクスポート、APIクエリを備えた監査ログ	対応する組織・管理イベントを対象とし、文書化された保持期間は180日。ランタイムAPIトラフィックやアプリケーションログではない
ガバナンスされたソース管理	Gitリポジトリ接続、OpenAPIインポート、バックアップ・同期、Gitネイティブコラボレーション	リポジトリ権限とブランチガバナンスはソース管理プラットフォーム側で設定する。OpenAPIとGitHubを同期する方法とGitに保存されたAPI仕様を保護する方法を参照
GitHub Enterprise Cloudデータレジデンシー互換性	対応するGitHub Enterprise Cloudデータレジデンシーテナントへの組織レベル接続	ルートの`*.ghe.com` SaaSテナントをサポートする。GitHub Enterprise Server、カスタムドメイン、ネストされたサブドメイン、URLパスは非対応。完全なレジデンシーやコンプライアンス保証として扱わない

ツールを選定する際は、機能数ではなく、要件と制御マトリックスに対する実際のカバレッジを評価してください。

実践的な90日ロードマップ

1〜30日目：ベースラインを確立する

APIポートフォリオの初期インベントリを作り、オーナーを割り当てる
リスク階層を定義し、パイロットドメインを選ぶ
5〜10個の最小制御に合意する
ID、アクセス、認証情報、ソース管理、証拠の現行フローを文書化する
例外テンプレートとレビュー頻度を決める

31〜60日目：実際のワークフローで試す

新規APIと選定した既存APIにベースラインを適用する
設計・ドキュメントの準拠例を公開する
SSO、プロビジョニング、RBAC、グループマッピングを設定する
ドキュメント、設計、認証情報、証拠の制御をテストする
準拠にかかる時間、失敗理由、未解決例外を測定する

61〜90日目：効果のあった仕組みを拡大する

パイロットの証拠と開発者フィードバックで制御を改善する
リスクに応じて対象ドメインを増やす
カバレッジ、適合性、例外、修正のダッシュボードを作る
高リスクAPIに詳細な制御を追加する
ランタイム連携、定期アクセスレビュー、ライフサイクル整理のロードマップを公開する

最初から包括的なフレームワークを作るより、チームが一貫して従える小さな制御セットから始める方が、学習と改善につながります。

APIガバナンスツールの選び方

ツールではなく、先に運用モデルと制御マトリックスを定義します。主な評価項目は次のとおりです。

組織のAPI仕様とプロトコルへの対応
設計標準、再利用可能なコンポーネント、品質チェック
ドキュメント、発見、テスト、ライフサイクルワークフロー
エンタープライズID、プロビジョニング、RBAC、チームマッピング
シークレットストレージ、ポリシー、検出、修正の連携
管理証拠、フィルタリング、エクスポート、API
Git、CI/CD、IDプロバイダー、Vault、ゲートウェイ、可観測性との統合
デプロイ方式、データロケーション、リポジトリ要件
例外処理とレポート
コンプライアンスへの道筋を明確にする開発者体験

すべてのランタイム機能と開発機能を1つのツールに集約する必要はありません。重要なのは、ツール間で適切なアーティファクトと証拠を交換でき、所有権のギャップを生まないことです。

要件ベースで比較する際は、APIガバナンスツールも参考にしてください。

APIガバナンスに関するFAQ

APIガバナンスとは簡単に言うと何ですか？

APIをライフサイクル全体で一貫性があり、安全で、発見可能かつ管理しやすい状態に保つための、ルール、責任、ワークフロー、証拠のセットです。

APIガバナンスは誰が所有すべきですか？

エグゼクティブスポンサーは技術または製品部門が担い、プラットフォームまたはイネーブルメントチームが共有ベースラインを所有する形が一般的です。

ドメインチームは自分たちのAPIに責任を持ち、セキュリティ、アーキテクチャ、法務、プライバシー、運用チームは、それぞれの領域に関する制御を担当します。

APIガバナンスポリシーの例は何ですか？

次のようなポリシーが考えられます。

責任あるオーナーを指定する
承認済みのAPI仕様を使う
標準認証パターンを採用する
ドキュメントを完全にする
後方互換性をレビューする
承認済みの認証情報ストレージを使う
最小権限アクセスを適用する
監査証拠を残す
非推奨期間を定義する

APIガバナンスは開発を遅らせますか？

設計の悪いガバナンスは開発を遅らせます。しかし、テンプレート、例、再利用可能なコンポーネント、セルフサービスチェック、リスク階層、明確な例外パスを提供すれば、繰り返しの判断と手戻りを減らせます。

APIガバナンスはAPI管理と同じですか？

いいえ。ガバナンスは、ポートフォリオ全体の意思決定権限、標準、ポリシー、証拠を定義します。API管理は通常、ゲートウェイ、ポータル、ランタイムポリシー、分析などを通じてAPIの公開・運用を担当します。

組織はどのように始めるべきですか？

次の順で始めます。

APIインベントリを作る
オーナーを指名する
リスク階層を定義する
小さな最小制御セットを決める
1つのドメインでパイロットする
結果を測定してから段階的に拡大する

APIチームの働き方にガバナンスを組み込む

APIガバナンスの目的は、信頼できるデリバリーを再現可能にすることです。

明確な所有権を定義し、ライフサイクル全体にリスクベースの制御を適用し、チームが標準に従えるテンプレートと例を提供し、証拠を使ってプログラムを継続的に改善してください。

Apidogは、API設計、ドキュメント、テスト、Gitワークフロー、コラボレーション、エンタープライズID、認証情報制御、管理証拠を共有プラットフォームに統合します。

Apidog Enterpriseを検討し、自社のAPIガバナンスフレームワークに各制御をどのように組み込めるか評価してみてください。

Gemini Omni 1.1 Flash: GoogleのGAビデオモデル最新情報

Akira — Fri, 28 Aug 2026 08:40:29 +0000

Googleは2026年8月27日、会話型動画モデルを一般公開しました。モデルIDはgemini-omni-1.1-flashで、6月30日にパブリックプレビューとして提供されたgemini-omni-flash-previewを置き換えます。プレビュー版を利用している場合は、2026年9月30日のプレビューエンドポイント停止までに移行してください。

今すぐApidogを試す

今回のGAリリースでは、プロダクション利用で不足していた機能が追加されました。

最大40秒のシーン拡張
最初と最後のフレームを指定するキーフレーム制御
低コストな360pドラフトモード
4Kアップスケーリング

Omniファミリーの背景は、Gemini Omniとは何かを参照してください。この記事では、Gemini Omni 1.1 Flashの実装に必要な変更へ焦点を当てます。

Gemini Omni 1.1 Flashでできること

Omni 1.1 Flashは、テキスト、画像、動画を入力として受け取り、動画を返します。

実行にはgenerateContentではなくInteractions APIを使用します。Interactions APIはステートフルなマルチターン生成に対応しているため、生成した動画を再アップロードせず、そのまま編集リクエストへ渡せます。

対応するタスクは次の5種類です。

テキストから動画：プロンプトから動画を生成
画像から動画：画像をオープニングフレーム、または動きのスタイルガイドとして使用
リファレンスから動画：最大3本の参照クリップ（各3秒以内）から、動き・見た目・キャラクターの一貫性を新しいシーンへ反映
編集：生成済み動画の内容を会話形式で変更
拡張：クリップの末尾に10秒追加

参照クリップの音声は無視され、動きと見た目だけが読み取られます。

シーン拡張では最大10秒のコンテキストを利用

プレビューモデルは、クリップの最後の1秒だけを参照して継続していました。そのため、色は維持できても、キャラクターが崩れたりカメラワークがリセットされたりする問題がありました。動画は拡張できても、ショットの連続性を保つのは困難でした。

Omni 1.1は、過去最大10秒のコンテキストを分析します。Googleはこれにより、「視覚的な一貫性と物語の一貫性の向上」を実現すると説明しています。拡張は10秒単位で行い、最大40秒まで累積できます。

制限もあります。

拡張できるのはクリップの末尾だけです。先頭への追加や途中への挿入には対応していません。
マルチターンインタラクションで以前の状態を保持していない場合、アップロード動画の入力は最大10秒です。

リクエスト形式や継ぎ目の確認方法は、40秒のシーン拡張ウォークスルーを参照してください。

最初と最後のフレームを指定する

最初と最後のフレーム、およびフレーム間の動きをプロンプトで指定し、2つの画像をつなぐ動画を生成できます。Googleは、カメラ軌道、ズームトランジション、ループクリップを主な用途として挙げています。

テキストから動画を生成する場合、出力は予測しにくいことがあります。キーフレーム制御では2つの固定点を与えられるため、モデルが解決すべき範囲を狭め、より予測可能な動画を作れます。

360pドラフトで生成コストを削減

Omni 1.1は、360p動画を720pより最大60%高速に、3分の1のコストで生成します。推奨ワークフローは次のとおりです。

360pでプロンプトを試す
構図・動き・内容を確認する
採用するプロンプトを720p、1080p、または4Kで再レンダリングする

動画生成は1秒あたりのコストが高く、プロンプト調整中の出力は多くの場合破棄されます。ドラフトを低コストで繰り返せることは、試行回数を増やしながら予算を抑えるうえで重要です。完全な料金の内訳では、1秒あたりの料金を確認できます。

解像度はレスポンス形式で指定します。1080pと4kはネイティブレンダリングではなく、生成フレームのアップスケールです。

利用できる場所

Omni 1.1 Flashは、次のサービスで利用できます。

開発者向けのGoogle AI StudioにあるGemini API
エンタープライズ向けのGemini Enterprise Agent Platform API
AI Plus、Pro、Ultraサブスクライバー向けのGoogle Flow
シーン拡張に対応したGeminiアプリ

Googleは、Adobe Firefly、Figma Weave、Runway、GMI Cloudをローンチパートナーとして発表しています。これらのサービスを利用している場合、すでにOmni 1.1 Flashへリクエストが送られている可能性があります。

APIに無料枠はありません。テキストFlashモデルにはAI Studioのレート制限付き無料利用枠がありますが、Omniは最初のリクエストから生成秒数に応じて課金されます。

モデル自体はYouTube ShortsとYouTube Createで無料利用できます。ただし、これらはAPIとは異なる制限を持つ製品です。Gemini Omniの無料アクセスに関する概要で、利用経路ごとの違いを確認できます。

まだできないこと

導入前に、次の制限を確認してください。

高度なプロンプト制御がない：システム指示、temperature、top_p、ストップシーケンス、ネガティブプロンプトには対応していません。除外したい内容は通常のプロンプトに記述します。
地域制限がある：欧州経済領域、スイス、英国では、動画のアップロードと編集、未成年者を含む画像の編集を利用できません。モデルが生成した動画は、これらの地域でも編集できます。
識別可能な人物を編集できない：特定の識別可能な個人の編集はブロックされます。
アップロード動画に会話を追加できない：アップロードした動画の無音拡張やマルチターン編集は可能ですが、他者がアップロードした動画を拡張する際に会話を追加することはできません。
推論に使える動画は1回につき1本：複数の入力動画をまたいだ推論には対応していません。
実質的に英語のみ：Googleは英語を完全サポートし、他言語は未テストとしています。

すべての出力には、視聴者には見えずプログラムで検出できるSynthIDウォーターマークが付与されます。出所を主張する製品では、この点を考慮してください。

Omni 1.1 FlashとVeo 3.1の違い

現在、Googleは同じAPIキーで2つの動画生成ファミリーを提供しています。

モデル	特徴
Omni 1.1 Flash	マルチターン編集に対応する会話型モデル
Veo 3.1	ネイティブ音声に対応するシネマティックレンダラー

Omniの720p動画は、標準的なVeo 3.1の約4分の1の秒単価です。一方、Veo 3.1にはOmniのようなマルチターン編集ループはありません。

用途別の選び方は、Gemini Omni 1.1 FlashとVeo 3.1の詳細比較を参照してください。既存のVeo統合を使っている場合は、Veo 3.1 APIガイドも引き続き利用できます。今回のリリースでVeoの機能が廃止されることはありません。

プレビューエンドポイントから移行する

gemini-omni-flash-previewを参照する機能は、2026年9月30日以降動作しません。通常はモデル文字列を1行変更するだけですが、次の2点も確認してください。

解像度のデフォルト：現在のデフォルトは720pです。360pと4Kは新しい選択肢なので、コードが固定出力サイズを前提としていないか確認します。
レスポンス形式：4MBを超える動画は、インラインのbase64ではなくURIで返されます。output_video.dataだけを読み取る実装では、高解像度動画の取得に失敗します。

安全な移行手順は次のとおりです。

モデルIDを環境変数に切り出す
APIクライアントにリクエストを保存する
プレビュー版とGA版のレスポンスを比較する
利用するすべての解像度で、データまたはURIの取得をテストする
2026年9月30日までにGA版へ切り替える

Apidogでは、モデルIDを環境変数として管理し、保存済みリクエストを環境ごとに切り替えて比較できます。Gemini Omni 1.1 Flash APIウォークスルーで設定手順を確認できます。

FAQ

Gemini Omni 1.1 FlashのモデルIDは？

gemini-omni-1.1-flashです。廃止されるプレビューIDはgemini-omni-flash-previewです。

いつリリースされましたか？

GA版は2026年8月27日、プレビュー版は2026年6月30日に提供されました。

無料ですか？

いいえ。Omniには無料枠がなく、すべての生成が課金されます。Gemini 3.6 Flashのようなテキストモデルには無料のAI Studioレーンがありますが、Omniにはありません。

動画の長さは？

通常は10秒のクリップを生成し、シーン拡張によって10秒単位で最大40秒まで延長できます。

音声も生成しますか？

ドキュメントは動画出力についてのみ説明しており、参照クリップの音声は無視されます。ネイティブ音声が必要な場合は、Veo 3.1 APIを利用してください。

自分で撮影した動画を編集できますか？

EEA、スイス、英国以外であれば可能です。入力できるのは最大10秒の動画で、Files APIにアップロードしてURIを渡します。

まとめ

Omni 1.1 Flashは、製品に組み込みやすくなった最初のOmniモデルです。シーン拡張はショットの一貫性を高め、キーフレーム制御は出力を予測しやすくし、360pドラフトは反復コストを抑えます。

移行時は、次の作業を先に済ませてください。

GAモデルIDを保存済みリクエストに設定する
使用予定の全解像度でレスポンス形式を確認する
base64とURIの両方を処理する
2026年9月30日までにプレビューエンドポイントから移行する

期限後ではなく、期限前に移行結果を検証するなら、Apidogをダウンロードしてください。

DEV Community: Akira

ETagとCache-ControlによるAPIキャッシング：条件付きリクエストでペイロードを削減する方法

HTTPキャッシュの3つの層

レイヤー1: 鮮度

レイヤー2: 検証

レイヤー3: 無効化

304 Not Modifiedのラウンドトリップ

1. 初回リクエスト

2. 初回レスポンス

3. 60秒後の再リクエスト

4. リソースに変更がない場合

APIで重要なCache-Controlディレクティブ

no-storeとno-cache

private

max-age

stale-while-revalidate

Strong ETagとWeak ETag

Strong ETag

Weak ETag

ETagの生成: ボディハッシュとバージョンカラム

レスポンスボディのハッシュ

バージョンカラムまたはupdated_at

楽観的並行性制御: If-Matchと412

CDNとプロキシの動作

Expressの例: ETagの返却とIf-None-Matchの処理

Apidogでキャッシュ動作を検証する

よくある質問

no-cacheとno-storeの違いは何ですか？

ETagはPOSTで機能しますか？

304レスポンスはAPIを高速化しますか？

ETagとLast-Modifiedのどちらを使うべきですか？

REST API命名規則：実践スタイルガイド

REST APIの命名規則：一貫性のあるエンドポイントを設計する10のルール

1. コレクションには複数形の名詞を使用する

2. パスから動詞を除外する

3. URLパスにはケバブケースを使用する

4. JSONの命名規則を一つ選び、文書化する

5. ネストは2レベルまでにする

6. フィルタリング、ソート、ページネーションはクエリパラメータに入れる

7. パスにメジャーバージョンを記述する

8. リソースIDを不透明に扱う

9. 非CRUDアクションをコントローラーリソースとしてモデル化する

10. ヘッダーとクエリパラメータの命名規則を統一する

ルールセット全体を一目で確認

大規模なコンベンションを適用する

よくある質問

RESTのURLは複数形と単数形のどちらにすべきですか？

JSONフィールド名にはcamelCaseとsnake_caseのどちらが優れていますか？

APIバージョンはURLに入れるべきですか、それともヘッダーに入れるべきですか？

REST APIパスで動詞が許容されることはありますか？

カーソルベースページネーション 対 オフセットページネーション：APIでの選び方

オフセットページネーションの仕組み

問題1：ページドリフト

問題2：深いオフセットはスキップする行をすべてスキャンする

カーソルベースページネーションの仕組み

トレードオフの概要

どちらを選ぶべきか？

実際のAPIがどのように対応しているか

レスポンスエンベロープの設計

Apidogで両方のスタイルをテストする

カーソルエンドポイント

オフセットエンドポイント

エッジケース

よくある質問（FAQ）

カーソルページネーションは常に優れているのか？

カーソルページネーションで合計件数を取得するには？

1つのエンドポイントで両方の方式を提供できるか？

カーソルのアンカー行が削除されたらどうなるか？

REST APIエラー処理ベストプラクティス：ステータスコード、RFC 9457、リトライ可能なエラー

REST APIのエラー処理を設計する：ステータスコード、Problem Details、再試行、テスト

1. エラーボディより先にステータスコードを決める

2. RFC 9457 Problem Detailsでエラー形式を統一する

3. 機械可読コードと人間向けメッセージを分離する

機械可読コード

人間向けメッセージ

4. エラー応答から機密情報を除外する

5. エラーを再試行可能または終端として定義する

6. 相関IDとエラー契約をバージョン管理する

リクエストIDを全リクエストに付与する

エラー契約をAPIと同じように管理する

`no-store`と`no-cache`

`private`

`max-age`

`stale-while-revalidate`

バージョンカラムまたは`updated_at`

楽観的並行性制御: `If-Match`と`412`

Expressの例: ETagの返却と`If-None-Match`の処理

`no-cache`と`no-store`の違いは何ですか？

カーソルベースページネーション対オフセットページネーション：APIでの選び方

`application/problem+json`とは何ですか？

`Retry-After`を尊重する

1. `Access-Control-Allow-Origin`ヘッダーがありません

2. ワイルドカード`*`と認証情報を併用しています

`Access-Control-Allow-Origin: *`はどこでも使えますか？