Web API設計の基準【2026年版】｜エラー・認証・バージョニング

2026年のWeb API設計は、チームごとの好みでエラーJSONや認可フローを増やす段階から、公開仕様と大規模公開APIがすでに収束した項目を既定値にする段階へ移っています。優先して固定したいのは次の5点です。

📑目次

1. 2026年のWeb APIは「好み」より「採用済み基準」で決める
2. エラー応答 — RFC 9457 problem+json を既定にする
3. 認可 — OAuth 2.1待ちにせず RFC 9700（Auth Code + PKCE）へ寄せる
4. 版管理と廃止告知 — pathメジャー vs 日付ヘッダ、Deprecation/Sunset
5. 契約・ページング・冪等性 — OpenAPI 3.2 とテーブルステークス
6. 採用判断表と移行チェックリスト
7. よくある質問（FAQ）
8. まとめ — 今日決めること

1. 機械可読なエラー
2. 安全な認可の既定
3. 版管理と廃止の機械可読化
4. 契約（OpenAPI）
5. 冪等性とページング

本記事は、一次仕様と独立整理を根拠に、新規APIのデフォルト選択と既存APIの移行チェックリストへ落とし込みます。

一次・公式ソース

• IETF RFC 9457（Problem Details）
• IETF RFC 9700（OAuth 2.0 Security BCP）
• IETF RFC 9745（Deprecation ヘッダ）
• GitHub Docs の REST API バージョン
• Google AIP-185
• OpenAPI Specification 3.2.0

独立整理

• Digital Applied
• Zenn の RFC 9457 解説

話題の発端となった解説記事は論点マップとして扱い、事実確認は上記の一次・独立ソースで行います。

この記事で学べること

---

2026年のWeb APIは「好み」より「採用済み基準」で決める

結論から言うと、自前API・B2B連携・自動化クライアント（AIエージェント含む）が増えるほど、アドホックなエラー形式・認可・版の揺れが運用コストとインシデントの主因になります。

基準を固定する目的は流行追随ではなく、次を実現することです。

• クライアント実装の分岐を減らす
• サポート期限と廃止を機械的に伝える
• 再試行を安全にする

実務では次の5点を「新規テンプレートの既定」として先に決めます。

1. エラーは Problem Details（RFC 9457）
2. 認可は Authorization Code + PKCE（RFC 9700）
3. 版管理は path major か date/header のどちらか一文で固定
4. 契約は OpenAPI 3.2 を SSOT
5. 書込系は Idempotency-Key、大規模一覧は cursor ページングを前提

以降の各節では、仕様の要点と既存APIでの移行シグナルをセットで示します。

---

エラー応答 — RFC 9457 problem+json を既定にする

HTTP APIのエラーボディは、RFC 9457 Problem Details（application/problem+json）を既定にするのが2026年の実務的な出発点です。

要点は次のとおりです。

• Standards Track として2023年7月に公開
• RFC 7807 を obsolete
• APIごとに私有のエラー文書を発明しない
• HTTP status の意味を再定義しない

標準メンバーと拡張

標準メンバーは次のとおりです。

• type（URI）
• title
• status
• detail
• instance

拡張メンバーで validation errors 配列や残高不足時の balance などを載せられます。

日本語の独立解説としては Zenn（keisuke333） が次を整理しています。

• type / status / title / detail / instance
• IANA problem-type レジストリ
• 複数問題の扱い

移行時の注意と読者アクション

注意点は次のとおりです。

• problem+json を返しても status と title が矛盾するとクライアント実装が壊れる
• type URI は安定させる
• 解決不能URI方針を先に決める

読者アクション:

1. 既存の { "error": "..." } 文字列レスポンスを inventory する
2. 共通 Problem Details ミドルウェアへ段階移行する

---

認可 — OAuth 2.1待ちにせず RFC 9700（Auth Code + PKCE）へ寄せる

2026年の新規クライアントは Authorization Code + PKCE を既定にし、password/ROPC や implicit 系を新規採用しない、というのが現時点の安全な既定です。

根拠は OAuth 2.1 の RFC 化待ちではなく、2025年1月公開の RFC 9700（BCP 240） です。

RFC 9700 が示す既定

RFC 9700 は OAuth 2.0 Security Best Current Practice で、RFC 6749/6750/6819 を更新します。

• Authorization Server は PKCE を MUST support
• public clients は PKCE MUST
• confidential clients は RECOMMENDED
• 危険・低安全モードは deprecate
• OAuth 2.1 draft がこれらの推奨を取り込む前提でも、現行BCPに従えば十分

制限と読者アクション

制限もあります。

• レガシー ROPC を残すなら期限付き例外と監視を明示する
• モバイル／SPA は public client 前提で PKCE 必須

読者アクション:

1. IdP／AS 設定で許可グラントを棚卸しする
2. 新規アプリの grant whitelist を Code+PKCE のみに固定する

---

版管理と廃止告知 — pathメジャー vs 日付ヘッダ、Deprecation/Sunset

版管理に単一の世界標準はありません。Google AIP-185 の path メジャー（/v1）と、GitHub の日付＋X-GitHub-Api-Version は両立する別流派です。

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

• 混在させず一文で選ぶ
• 廃止をブログだけでなく機械可読ヘッダで伝える

出典

日付ヘッダ方式（GitHub）

GitHub Docs の要点は次のとおりです。

• バージョン名はリリース日（例: 2026-03-10）
• クライアントは X-GitHub-Api-Version を送る。省略時デフォルトは 2022-11-28
• 未サポート版は 410 Gone
• 新版リリース後、旧版を少なくとも24か月サポート
• 終了接近時に Deprecation / Sunset ヘッダ

path メジャー方式（Google AIP-185）

Google AIP-185 の要点は次のとおりです。

• REST でメジャーを URI 先頭 path に置く（v1）
• v1.0 / v1.1 を公開面に出さない
• 新メジャーは旧メジャーに依存禁止
• 移行中は複数メジャーを同時提供
• 旧版は十分な告知付き deprecation period の後に停止

廃止告知（RFC 9745 + Sunset）

廃止告知側では RFC 9745（2025-03）が次を標準化します。

• Deprecation ヘッダを Structured Fields Date として定義（例: Deprecation: @1688169599）
• deprecation link relation で移行ドキュメントを指す
• Sunset（RFC 8594）と併用

ヘッダ自体は振る舞いを変えない合図なので、サポート期限と移行リンクとセットで運用してください。

読者アクション:

1. 自APIの版戦略を「path major」か「date/header」かに一文で決める
2. 廃止時のヘッダとリンク関係を OpenAPI／実装に先に書く

---

契約・ページング・冪等性 — OpenAPI 3.2 とテーブルステークス

API説明のデファクトは OpenAPI 3.2.0（2025-09-19、OpenAPI Initiative / Linux Foundation）です。

• 言語非依存の HTTP API 記述（JSON/YAML）
• docs / codegen / test の契約源にする
• 「Swagger 2.0」名称だけに依存した古い前提から、現行 OAS 行へ揃える

2026年コンセンサス（Digital Applied）

独立二次ソースの Digital Applied（2026-06-13） は、2026年のコンセンサスを次のように要約しています。

• エラー: RFC 9457 problem+json
• ページング: deep OFFSET より cursor（大規模で scan-and-discard を避ける）。GitHub Link header が本番パターン例
• Idempotency-Key: Stripe 由来のデファクト（V4 UUID、255文字上限、約24h保持。endpoint 実行開始後にキャッシュ）
• 版管理: Stripe date pin / GitHub ヘッダ型の隔離
• 契約: OpenAPI 3.2

制限と次の一手

制限として、次を仕様に書かないとクライアントが再試行できません。

• Idempotency-Key の保持時間
• キー空間
• 「いつからキャッシュするか」
• cursor の不透明性と期限

読者アクション:

1. 書込系 POST/PATCH に Idempotency-Key を必須化する
2. 一覧APIの deep OFFSET をメトリクスで監視する
3. cursor 移行の優先度を決める

---

採用判断表と移行チェックリスト

次の表は、新規APIの既定候補と、既存APIで移行を検討すべきシグナルを並べた実務マップです。

領域別の既定候補

領域	2026年の既定候補	主な根拠	既存APIでの移行シグナル
エラー	RFC 9457 application/problem+json	RFC 9457 / Zenn解説	文字列 error や独自JSONがクライアント分岐を増やしている
認可	Authorization Code + PKCE	RFC 9700 BCP 240	ROPC/implicit が残存、public client に PKCE 無し
版管理	path major（AIP-185）または date/header（GitHub）	AIP-185 / GitHub Docs	URLとヘッダが混在し、サポート期限が文書のみ
廃止告知	Deprecation + Sunset ヘッダ	RFC 9745 / GitHub運用	ブログ・メールのみでクライアントが検知不能
契約	OpenAPI 3.2 を SSOT	OAS 3.2.0	手書きWikiと実装が乖離、codegen不能
ページング	cursor（大規模）	Digital Applied / 大規模API慣行	deep OFFSET のレイテンシ・負荷悪化
冪等性	Idempotency-Key（書込系）	Digital Applied（Stripe由来慣行）	再試行で二重課金・二重作成が起きる

出典（2026年8月時点）

• RFC 9457
• RFC 9700
• RFC 9745
• GitHub Docs
• Google AIP-185
• OpenAPI 3.2.0
• Digital Applied

今週から使えるチェックリスト

1. 公開・社内APIの一覧を作り、エラー形式／許可グラント／版の出し方／OpenAPI有無を1行ずつ記入する
2. 新規APIテンプレートのデフォルトを problem+json・Code+PKCE・版戦略一文・OpenAPI 3.2 に固定する
3. 書込系エンドポイントに Idempotency-Key 要件（形式・保持時間・衝突時応答）を仕様化する
4. 廃止予定のフィールド／版に Deprecation/Sunset と移行リンクを付ける担当と期限を決める
5. deep OFFSET の遅いクエリをメトリクスで洗い、cursor 化の優先度を付ける
6. クライアントSDK／エージェント向けに「未サポート版は 4xx/410」「problem type のカタログ」をREADMEに書く
7. 四半期ごとに RFC/OAS と IdP 設定の差分レビューをカレンダーへ入れる

---

関連記事:

• fzf・ripgrep・ghで作る高速ターミナル開発環境
• Open Knowledge Format（OKF）とは？エージェント向けMarkdown知識仕様の導入判断
• MLOpsの継続的学習とエージェント評価｜Demo Hellを避ける実務設計

よくある質問（FAQ）

Q1. RFC 9457 は必須規格か。まだ独自エラーJSONでよいか？

法的必須というより、HTTP APIの機械可読エラーの Standards Track 標準です。新規APIは problem+json を既定にし、既存はゲートウェイ／ミドルウェアで段階移行するのが安全です（RFC 9457）。

Q2. OAuth 2.1 のRFCが出るまで待つべきか？

待たないでください。RFC 9700（2025-01, BCP 240）が現行のセキュリティBCPで、ASのPKCE必須や危険グラント非推奨をすでに示します。2.1 draft はその方向を取り込む前提です（RFC 9700）。

Q3. 版管理は GitHub 方式と Google AIP のどちらが正しいか？

どちらも正しい流派です。外部開発者向けで日付ピン留めが要るなら header/date、リソース指向でメジャー互換を切るなら path v1。混在させず一文で選びます（GitHub Docs / AIP-185）。

Q4. Deprecation ヘッダだけでAPIを止めてよいか？

ヘッダ自体は振る舞いを変えない合図です。Sunset やサポート期限、移行ドキュメント（deprecation link）とセットで運用します（RFC 9745、GitHubの24か月目安）。

Q5. OpenAPI は 3.0 のままで問題ないか？

3.x 系でも契約SSOTになっていれば運用可能です。ただし 2025-09 の現行公開線は 3.2.0 です。新規テンプレートやツールチェーン更新時は 3.2 へ寄せます（OAS 3.2.0）。

Q6. Idempotency-Key は決済API以外でも必要か？

再試行され得る作成・更新・副作用のあるPOST全般で有効です。キー形式（V4 UUID等）、長さ上限、保持時間（例: 約24h）、実行開始後キャッシュを契約に書きます（Digital Applied の整理）。

---

まとめ — 今日決めること

2026年のWeb API設計は、次を既定値セットとして固定する段階です。

• エラー（9457）
• 認可（9700/PKCE）
• 版＋廃止（AIP or GitHub + 9745/Sunset）
• 契約（OpenAPI 3.2）
• 冪等／ページング

今週中に「API一覧 × 7領域」の表を1枚作り、新規テンプレートのデフォルトを更新するのが最短の次アクションです。

• 人気記事の雰囲気だけで全エンドポイントを一括破壊的変更する必要はない
• 一次は RFC／公式、二次は独立整理を使う
• 個別のセキュリティ設計は脅威モデルに応じて検証する

優先チケットの例:

1. エラー形式の共通化
2. グラント棚卸し
3. 版戦略の文書化
4. OpenAPI 3.2 を SSOT 化
5. Idempotency-Key と Deprecation ヘッダの実装