Web API設計の現在地2026

311

Last updated at 2026-08-14Posted at 2026-08-07

Web API設計の現在地 2026、いま従うべき標準とデファクトの一覧

Web API設計を調べると、検索上位に出てくる記事が2015〜2019年あたりで止まっていることが多いです。その間にエラーレスポンスの標準ができ、OAuthのグラントタイプは選択基準が変わり、APIの廃止告知にまでRFCが生えました。

この記事では、Web API設計の主要な領域ごとに「2026年時点でいま従うべきものはどれか」を一次情報（RFC、IETFのドラフト、大手APIの実装）で確認した結果をまとめます。きっかけは2014年の『Web API: The Good Parts』を読んで、そこにあった「仕様に従う、仕様がなければデファクトに従う」という指針の、その仕様とデファクトが今どこにあるのか気になったことでした。

全体マップ

「その領域で何をすればいいか」と「その根拠はどこにあるか（正式なRFCなのか、標準がなくデファクトなのか）」を先に一覧にしておきます。詳細は各セクションで確認していきます。

領域	どうすればいいか	根拠はどこにあるか
エラーレスポンス	Problem Details 形式で返す	RFC 9457（2023年に標準化）
日時フォーマット	`2026-08-07T12:34:56Z` 形式で返す	RFC 3339（20年以上変わらず現役）
メソッド・ステータスコード	迷ったら RFC 9110 を引く	RFC 9110（2022年。旧 2616/7231 を統合）
認証・認可	Authorization Code + PKCE。ログイン用途は OIDC を重ねる	RFC 9700（2025年、BCP 240）。OAuth 2.1 ドラフトへ統合中
バージョニング	基本はパスに `v1`。不特定多数向け公開APIなら日付ベースを検討	標準なし。Google AIP-185 と GitHub/Stripe の実装
廃止告知	Deprecation / Sunset ヘッダで機械可読に伝える	RFC 9745（2025年）/ RFC 8594（2019年）
ページネーション	カーソル方式にする	標準なし。GitHub/Stripe の実装がデファクト
レートリミット	429 と `X-RateLimit-*` 系ヘッダを返す	429 は RFC 6585。残量ヘッダは標準なし（標準化が進行中）
冪等キー	`Idempotency-Key` ヘッダを受け付ける	標準化は停滞中。Stripe の実装がデファクト
API記述	OpenAPI で書く	デファクト。Linux Foundation 傘下の OpenAPI Initiative が仕様を管理（現行 3.2.0）

エラーレスポンス、RFC 9457 Problem Details

いちばん大きく変わった領域がここです。かつてエラーレスポンスの形式は各サービスが独自に設計するものでした。{ "error": { "code": 123, "message": "..." } } 型、エラー配列型といったいろいろな流派が生まれたのは、単に標準が存在しなかったからで、2023年のRFC 9457（初出は2016年のRFC 7807）でこの状況は終わっています。

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

{
  "type": "https://example.com/errors/insufficient-funds",
  "title": "残高が不足しています",
  "status": 403,
  "detail": "残高は30ポイントですが、50ポイント必要です",
  "instance": "/accounts/12345/transfers/67890"
}

ポイントは2つあります。

まず、HTTPステータスコードとアプリ固有のエラー識別子が1つのボディで両立していること。status にトランスポート層のカテゴリ、type に「具体的に何が起きたか」のURIが入ります。この2つは別レイヤーの情報で、どちらか片方では足りません。

もうひとつは拡張フィールドが公式に認められていることです。バリデーションエラーのようにフィールド単位の詳細が要る場合は、独自フィールド（errors 配列など）を足してよい仕様になっています。

フレームワーク側の足場は言語圏でかなり差があります（2026年8月時点、各公式ドキュメントで確認）。

フレームワーク	Problem Details 対応
Spring Framework 6 / Boot 3	`ProblemDetail` クラスを標準搭載。組み込み例外の自動 problem+json 化は `spring.mvc.problemdetails.enabled=true` の opt-in
ASP.NET Core	`[ApiController]` のエラーは `ProblemDetails` へ自動変換（デフォルト有効）。Minimal API は `AddProblemDetails()` を呼ぶ（.NET 7 から）
NestJS	組み込み対応なし。既定は `{ statusCode, message }` 形式。寄せるなら例外フィルタで自前実装
Express / Fastify / Hono	組み込み対応なし。既定のエラー形式はそれぞれ独自

JavaやC#の世界では標準がフレームワークに入り始めている一方で、JS/TS系のフレームワークにはまだ入っていません。JS/TSでAPIを書いているなら、RFC 9457 に寄せるかどうかも含めて、エラー形式を決めるのは依然として設計者の仕事です。

この領域は深掘り記事を書きました。ボディだけでなくステータスコード・ヘッダーを含めた3層それぞれの正典と、標準をプロジェクトに定着させる方法まではこちらです。

日時フォーマット、RFC 3339 のまま

日時は今も RFC 3339（2026-08-07T12:34:56Z）に従います。UTCで Z を付けて返し、表示時にクライアント側でローカライズする分担も含めて、20年以上変わっていません。ISO 8601 との関係は、RFC 3339 の方が曖昧さを排した実用プロファイルという位置づけで、Web APIで使うのはこちらです。

メソッド・ステータスコード、正典は RFC 9110

HTTPそのものの仕様は2022年に再編されています。長く引用されてきた RFC 2616（1999年）とその後継の RFC 7230番台（2014年）は、RFC 9110（HTTP Semantics）・9111（Caching）・9112（HTTP/1.1）に統合されて置き換わりました。メソッドとステータスコードの意味論の現行の正典は 9110 で、標準としての格も Internet Standard に上がっています。

実務での使い方はシンプルで、ステータスコードの選択に迷ったら 9110 の該当セクションを引きます。「400番台はクライアント起因、500番台はサーバ起因」という原則の出典もここです。APIで頻出のコードのなかでは 429 Too Many Requests が例外で、こちらは追加ステータスコードを定義した RFC 6585（2012年）が出典になります。

副次的な使い道として、資料の鮮度を測る目印にもなります。RFC 2616 を引いている解説は、HTTP仕様が2世代前だった時点の記事だと分かります。

認証・認可、変わったのはグラントタイプの選択基準

現行の標準は OAuth 2.0（RFC 6749、2012年）です。骨格となる4つのロールやトークンの考え方は当時から変わっていませんが、グラントタイプの選択基準が大きく変わりました。古い記事を信じると事故るのはここです。

場面	かつて	2026年
SPA	Implicit グラント	非推奨。Authorization Code + PKCE を使う
ID/パスワードを直接預かる	ROPC あり	使用禁止（MUST NOT）
PKCE	モバイル向けの追加対策	パブリッククライアントは必須。それ以外にも推奨

この選択基準には、いまや正式なRFCの根拠があります。RFC 9700「Best Current Practice for OAuth 2.0 Security」（2025年1月、BCP 240）が、ROPC を MUST NOT、Implicit を条件付きの SHOULD NOT と規定し、パブリッククライアントには PKCE を必須にしました（認可サーバ側の PKCE サポートも必須です）。名前をよく聞く OAuth 2.1 は、この内容を OAuth 2.0 本体の仕様へ統合し直しているドラフトで、2020年から議論が続いて2026年8月時点で rev 15、まだRFCではありません。つまり 2.1 のRFC化を待つ必要はなく、従うべき文書は既に発行されています。

もうひとつ、OAuth 2.0 は認可の仕組みであって認証ではありません。「ログインに使う」なら上に OpenID Connect が乗ります。

バージョニング、パスの `v1` と日付ベースの二大流派

バージョニングに標準仕様はなく、完全にデファクトの世界です。主要サービスを実際に叩いて現在の方式を確認しました。

サービス	方式	実測
GitHub	日付 + ヘッダ	`x-github-api-version-selected: 2022-11-28`
Stripe	日付 + ヘッダ	`2026-07-29.dahlia`
Shopify	日付をパスに	`2026-04` 〜四半期ごと
Google	メジャー番号をパスに	AIP-185 で `v1` を必須と規定
Microsoft Graph	メジャー番号をパスに	`/v1.0/` `/beta/`
Azure	日付をクエリに	`?api-version=2023-01-01`

パス方式が数では多数派のまま、不特定多数の外部開発者を抱える公開API側（GitHub、Stripe、Shopify）が日付ベースに寄っています。GitHub が象徴的で、昔の Accept: application/vnd.github.v3+json から2022年に日付ヘッダ方式へ移りました。

v1 → v2 の一括切り替えは全ユーザーの同時大移動を要求するので現実には起きず、v1 が永遠に残ります。日付ベースは変更を小さく刻んで各ユーザーが自分のペースで上がるモデルで、サーバ側が変換層で差分を吸収します。そのコストを払えるか、クライアントを自分で掌握しているかで選ぶことになるでしょう。社内・自社アプリ向けならパス方式の弱点は出ません。

APIの終わらせ方、Deprecation と Sunset ヘッダ

バージョニングの記事は世の中に山ほどあるのに、その続きにある「終わらせ方」はほとんど書かれていません。実はここも標準化されています。「このAPIは非推奨です」を伝える Deprecation ヘッダ（RFC 9745、2025年）と、「この日時に停止します」を伝える Sunset ヘッダ（RFC 8594、2019年）です。

Deprecation: @1735689600
Sunset: Sun, 01 Aug 2027 00:00:00 GMT
Link: <https://example.com/docs/migration>; rel="deprecation"

Deprecation は「いつから非推奨か」をUnixタイムスタンプで、Sunset は「いつ停止するか」をHTTP日付形式で持ちます。Link ヘッダで移行ドキュメントも案内できます。

廃止告知をブログとメールでやっても、そのAPIを実際に叩いているコードには届きません。レスポンスヘッダに載せれば、クライアント側のログと監視にそのまま残ります。通知先が「開発者のメールボックス」から「クライアントの実行ログ」に変わるのがこの2つのヘッダの価値で、廃止予定のエンドポイントを抱えているなら、次の廃止からすぐ使えます。

ページネーション、カーソル方式が主流

ページネーションにも標準仕様はありませんが、デファクトの答えは固まっていて、大量データや無限スクロールならカーソル方式（絶対位置指定）を選びます。

昔ながらのオフセット方式（?page=3 や ?offset=100&limit=20）には問題が2つあります。まず後半のページほど遅くなること。OFFSET 100000 はDBが10万件を実際に読んでから捨てる動きになるので、深いページほど線形に重くなります。もうひとつはズレること。ページ1を見ている間に新しいデータが1件挿入されると全体が1つずれて、ページ2で同じレコードを二重に見たり、逆に読み飛ばしたりします。

カーソル方式は「最後に見たID」を基準に WHERE id < :cursor ORDER BY id DESC LIMIT 20 で取るので、インデックスで直接その位置に飛べて何ページ目でも一定速度、途中の挿入・削除でもズレません。トレードオフは「5ページ目に飛ぶ」ができないことで、ページ番号ジャンプが要る管理画面ならオフセット方式にも出番が残ります。

次ページの伝え方は GitHub の Link ヘッダが参考になります。

Link: <https://api.github.com/repositories?since=369>; rel="next"

ページネーションの方式そのものに標準はありませんが、この伝え方の部品には標準があり、Link ヘッダと rel="next" は RFC 8288（Web Linking）で定義されています。かつて話題になった HATEOAS（レスポンスに次のアクションのリンクを含める設計思想）は全面採用こそ普及しませんでしたが、この rel="next" という形で部分的に生き残っています。

ひとつ注意があるとすれば、ページネーション方式はAPIの外部仕様なので、後から変えると全クライアントの改修になります。最初にどちらか決めておきたい領域です。

レートリミットと冪等キー、標準化が実装を追いかけている領域

この2つは面白い状態にあります。実運用のデファクトが先に固まっていて、標準化が後から追いかけています。

レートリミットで決まっているのは、超過時に 429 Too Many Requests を返すこと（RFC 6585、2012年）と、回復までの時間を Retry-After で伝えることまでです。残量を伝えるヘッダには標準がなく、X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset という X- 付きの形が各社デファクトとして定着しています。

IETF の httpapi ワーキンググループはこの標準化を進めていますが（2026年8月時点で rev 11 / Active のドラフト）、意外なことに、ドラフトが定義するのは既存デファクトの X- を取った3ヘッダ形式ではありません。そもそも X- プレフィックスという慣行自体が RFC 6648（2012年）で新規採用を非推奨とされていて、デファクトをそのまま追認する標準化にはなりようがなかったのです。ドラフトが定義するのは RateLimit-Policy（制限のルール）と RateLimit（現在の残量）の2つで、Structured Fields を使ったこういう形になります。

RateLimit-Policy: "default";q=100;w=10
RateLimit: "default";r=50;t=30

q が割り当て量、w が時間窓（秒）、r が残量です。t は実効ウィンドウと呼ばれ、「この先 t 秒間は r を超えて使えない」という制約を表します。X-RateLimit-Reset のような「リセットまでの残り秒数」ではなく、t 秒後に全量が回復する保証はありません（値は次のレスポンスで変わりうる、と仕様に明記されています）。つまり標準化が完了しても X-RateLimit-* からの乗り換えは機械的な改名では済みません。今実装するなら X-RateLimit-* 系のデファクトに合わせておき、ドラフトの完成を待って対応を判断するのが現実的な線でしょう。

冪等キーはさらに極端で、Idempotency-Key ヘッダの標準化ドラフトは rev 07 が2026年4月に期限切れ（Expired）となり、標準化のプロセス自体が止まっています。それでも冪等キーは決済系APIの必須機構として現役で、Stripe のドキュメントが事実上の仕様書として参照され続けています。

その Stripe の仕様を要点だけ引くと、対象は POST のみ。キーには十分ランダムな文字列（v4 UUID など、最大255文字）を使い、同じキーの再送には最初のリクエストの結果（ステータスコードとボディ）を、成功・失敗を問わずそのまま返します。同じキーで異なるパラメータを送るとエラーです。キーは24時間経過後に削除される可能性があり、削除後の再利用は新規リクエストとして処理されます。つまり恒久的な重複排除ではなく、リトライを安全にするための短期の仕組みとして設計されています。各社の実装もおおむねこの形に倣っています。

標準化が追いつかない領域では、よくできた実装が仕様書の代わりになります。この2つはその実例で、RFCを探して見つからなくても諦めずに、デファクトの現物（大手APIのリファレンス）を探しに行く価値があります。

API記述、OpenAPI 3.2.0

API仕様の記述形式は OpenAPI がデファクトで、現行の最新は 3.2.0（2025年9月）です。「Swagger」の名前で覚えている場合はバージョン2.0の世界で止まっているので、名前ごと更新しておきたいところです（Swagger 2.0 が OpenAPI Initiative に寄贈されて OpenAPI になりました）。

デファクトと言える根拠も、検証できる範囲で挙げておきます。仕様を管理する OpenAPI Initiative は Linux Foundation 傘下のベンダー中立な組織で、Google、Microsoft、IBM、Bloomberg、SAP、Salesforce などが参画しています。提供する側では、GitHub と Stripe が自社APIの公式 OpenAPI 記述をリポジトリで配布しています。フレームワーク側では FastAPI が OpenAPI 生成を設計の中核に組み込み、ASP.NET Core も .NET 9 以降はテンプレート標準で生成を持ちます（Java は springdoc-openapi というコミュニティ製ライブラリが定番です）。採用率を示す独立の調査データは見つからなかったので何％という話はできませんが、作る側と配る側の両方でここまで土台になっている形式は他にありません。

位置づけも変わりました。かつてのSwaggerは「APIドキュメントを綺麗に表示するもの」でしたが、今の OpenAPI はスキーマから型付きクライアントやサーバスタブを生成する起点で、ドキュメントはその副産物という扱いに近いです。

レスポンスのデータ形式そのものについても現在地を書いておくと、公開Web APIはJSON固定が主流になりました。かつて紹介されていた「Accept ヘッダでJSONとXMLを選ばせる」設計は、仕様をシンプルに保つ方向に負けて廃れています。形式の多様性は別の場所に移っていて、社内のサービス間通信は gRPC/Protocol Buffers、クライアント主導でフィールドを選ばせたい場面は GraphQL、と用途で分化しました。

標準がない領域の調べ方

ここまで見てきたとおり、RFCで決まっている領域は素直にRFCに従えばいい。問題はバージョニングやページネーションのような標準がない領域で、そこで何を参照するかも確認しておきました。

企業のAPI設計ガイドでは、体系性なら Google AIP (API Improvement Proposals) です。番号付きのルール集で、バージョニングの v1 必須（AIP-185）のように個別に引けます。読み物として優れているのは Zalando RESTful API Guidelines で、「なぜそうするか」の理由が丁寧に書かれています。古株の Google JSON Style Guide も、リポジトリを見ると2025年に社内版から同期されており、放置ドキュメントではなく現役でした。

新しい標準の定点観測先はIETFの httpapi ワーキンググループで、レートリミットや冪等キーのようなWeb API周りの標準化はここに集まっています。

まとめると、調べる順番はこうなります。まずRFCがあるか（RFC Editor）。なければ標準化が進行中か（IETF Datatracker）。それも無ければデファクトの現物（Google AIP や GitHub / Stripe のような大手APIの実装）を見る。この記事の各領域は、この手順を2026年8月時点で一巡した結果です。