2026.09.02 API

API設計とは？リソース定義からURI・スキーマ・エラー・版管理までの実装手順

API設計とは、実装に入る前にリソース・URI・HTTPメソッド・スキーマ・エラー応答・バージョニング・認証の7点を決め切る工程を指します。エンドポイント一覧を作る作業と捉えてしまうと、公開後に破壊的変更を繰り返すAPIになりがち。この記事では、業務モデルをリソースへ分解する手順から、RFC 9457に沿ったエラー本文の項目設計、OpenAPI 3.2.0での記述、版管理の選び方までを工程順に並べます。社内APIで設計をどこまで薄くしてよいかも、条件付きで示しました。

まとめ：API設計で先に決める7項目と着手順

API設計で先に確定させるのは、リソース定義、URIの命名規則、HTTPメソッドの割り当て、リクエスト・レスポンスのスキーマ、エラー応答の形式、バージョニング方式、認証・認可の7項目です。この順で決めると後工程の手戻りが減ります。認証から議論を始めると、守る対象であるリソースの粒度が定まらないまま方式だけが決まってしまいます。

判断の軸は「後から変えられるか」。URIの構造とエラー本文の形式は公開後に変えるとクライアント改修を強制するため、着手時点で決め切ります。ページネーションの上限値やレート制限の閾値は、運用しながら調整できます。

社内システム間の連携APIなら、OpenAPIドキュメントとエラー形式の統一だけ守り、HATEOASやカスタムメディアタイプは見送って構いません。外部公開やパートナー連携では、破壊的変更の検知とサポート期限の告知が加わります。この線引きを最初に宣言しておくと、設計会議が長引きません。

API設計とは何を決める工程か：実装・仕様書作成との作業範囲の違い

API設計という言葉は、エンドポイント一覧の作成から通信方式の選定まで広く使われます。ここでは工程の境界を先に固定します。

API設計が扱う7つの工程とコーディング着手前に確定させる範囲

API設計が扱うのは、リソース定義、URI設計、HTTPメソッド割り当て、スキーマ定義、エラー応答設計、バージョニング方式、認証・認可方式の7工程です。実装言語やフレームワークの選定、データベースの物理設計、インフラ構成は含みません。境界を引く基準は「クライアント側から観測できるか」の一点。クライアントが見る名前・形・振る舞いは設計工程、サーバ内部の都合は実装工程に置きます。

設計工程を省いて実装したAPIで起きる3つの典型的な手戻り事例

設計を省いた場合の手戻りは、ほぼ3つの型に収まります。1つ目は命名の不統一で、userId と user_id が同一API内に混在し、クライアント側が変換層を書く羽目になる型。2つ目はエラー形式の不統一で、あるエンドポイントは200番台でエラー内容を返し、別のエンドポイントは500番台の素のHTMLを返す型です。

3つ目が最も高くつきます。リソースの粒度を決めずに画面単位でエンドポイントを生やし、画面改修のたびにAPIが増える型。100本を超えた段階で、どれが使われているかを誰も把握できなくなります。REST原則そのものはRESTとは？REST APIの仕組みと6原則で扱っているため、原則の確認はそちらを参照してください。

リソース定義とURI設計・HTTPメソッド割り当ての具体的な進め方

設計の起点はリソースの洗い出しです。ここでの分解粒度が、URI・メソッド・スキーマすべての形を決めます。

リソースの洗い出しと名詞への分解：業務モデルからの写し取り方

リソースは、業務で名前が付いている概念をそのまま名詞として拾います。受注管理であれば注文、注文明細、顧客、在庫、出荷指示。画面名やユースケース名から拾うと「注文登録画面API」のような動詞混じりの単位になり、複数画面から呼ばれた瞬間に破綻します。判断基準は「その名詞を業務担当者が会話で使っているか」に置くと外しません。

拾った名詞は、独立して識別子を持てるかで一次リソースとサブリソースに分けます。注文明細は注文なしに存在しないためサブリソース、顧客は単独で参照されるため一次リソース。この分類がそのままURI階層になります。名詞中心に組み立てる考え方の背景はリソース指向アーキテクチャ（ROA）とRESTの違いで整理しています。

URIの命名規則：複数形・小文字・ハイフンとネスト2階層の目安

URIの命名は4つの規則で固定します。名詞は複数形（/orders）、小文字のみ、単語区切りはハイフン（/shipping-instructions）、拡張子を付けない。動詞をパスに入れないことも同列です。表記ゆれを許すと、クライアント側が推測でURLを組み立てられなくなります。

ネストは2階層までを目安にします。/orders/{orderId}/items までは自然に読めますが、/customers/{id}/orders/{id}/items/{id}/shipments では途中のIDが検証されているか読み取れません。3階層目が欲しくなったら、そのサブリソースを一次リソースへ昇格させ、クエリパラメータで絞り込む形に置き換えます。命名規則の当てはめ方と差し戻しの判定基準はREST API設計のベストプラクティス｜URI・冪等性・エラー応答のレビュー基準にまとめました。

HTTPメソッドの割り当てと冪等性・安全性の判定基準（RFC 9110）

メソッドの割り当ては、RFC 9110（HTTP Semantics・2022年6月発行）が定義する安全性と冪等性で判定します。GETとHEADは安全かつ冪等、PUTとDELETEは安全ではないが冪等、POSTはどちらでもありません。PATCHも冪等性は保証されない扱いです。

メソッド	安全	冪等	主な用途
GET	はい	はい	リソース取得
POST	いいえ	いいえ	作成・非CRUD操作
PUT	いいえ	はい	全体置換
PATCH	いいえ	いいえ	部分更新
DELETE	いいえ	はい	削除

この表を設計時に見る理由は、リトライ設計と直結するからです。ネットワーク断でレスポンスを受け取れなかったとき、冪等なメソッドはそのまま再送できます。POSTで作成する場合は再送で二重登録が起きるため、クライアント生成の一意キーをヘッダで受け取り、サーバ側で重複を弾く設計を添えてください。

CRUDに収まらない操作の表現：カスタムメソッドとサブリソース

「注文を確定する」「パスワードをリセットする」のような操作は、CRUDのどれにも当てはまりません。選択肢は2つ。状態そのものをサブリソース化して PUT で置き換える方式と、コロン区切りのカスタムメソッドを許す方式です。前者は /orders/{id}/status を confirmed に更新する形、後者は /orders/{id}:confirm の形になります。

社内APIなら状態のサブリソース化を推します。状態遷移の履歴を後からリソースとして取得したくなる場面が多いためです。カスタムメソッド方式はGoogleのAPI設計指針で標準化されており、判断材料はGoogle API設計ガイドの概要にまとめています。1つのAPI内で両方式を混在させないでください。

スキーマ設計とOpenAPI記述で固めるリクエスト・レスポンス構造

リソースとメソッドが決まったら、やり取りするデータの形を定義します。文章で書くと解釈が割れるため、機械可読な形式へ落とします。

OpenAPI 3.2.0での記述単位とスキーマファースト運用の進め方

記述形式はOpenAPI Specificationが事実上の標準です。2026年9月時点の最新版は3.2.0（2025年9月19日公開）。3.1系以降はJSON Schemaとの互換が取れているため、バリデーション定義をそのまま実装へ持ち込めます。記述単位はエンドポイント単位ではなく、components配下のスキーマ定義を先に作り、各エンドポイントから参照する形に。同じ「注文」の形が3箇所に重複すると、変更時に片方だけ直す事故が起きます。

設計書を先に確定させ、サーバとクライアントを並行開発する進め方についてはスキーマファーストとは？OpenAPI起点の並行開発と破壊的変更検知で手順を扱っています。並行開発を狙うなら、モックサーバの生成とCIでの差分検知をセットで組み込んでください。設計書だけ先に書いて実装が乖離すると、ドキュメントが信用されなくなります。

レスポンス構造の決め方：ページネーションと部分取得の指定方式

一覧取得のレスポンスは、配列を裸で返さず、オブジェクトで包んで件数やページ情報を同居させます。裸の配列で公開したAPIに後からメタ情報を足すと、それ自体が破壊的変更。包む形なら、キー追加だけで拡張できます。

ページネーションはオフセット方式とカーソル方式の2択です。オフセット方式（page・per_page）は実装が軽く総件数を返せる反面、データ更新中のページ送りで重複や取りこぼしが起きます。カーソル方式は整合性を保てる代わりに任意ページへ飛べません。管理画面向けはオフセット、大量データの同期用途はカーソルという切り分けが扱いやすい判断。1ページの上限は既定20件・上限100件のような形にし、運用中に動かせる余地を残します。

エラー応答の設計基準：ステータスコードとRFC 9457の使い分け

エラー設計は後回しにされたまま公開されがちな領域です。クライアント側の分岐処理がここで決まるため、正常系と同じ密度で詰めます。

ステータスコードの選定基準：400・404・409・422の使い分け

4xx系の選定で迷うのは、リクエスト構文は正しいが業務ルールに反する場合の扱いです。基準はこう置きます。JSONとして壊れている、必須項目が無いなど構文レベルの不備は400。指定IDのリソースが存在しないなら404。在庫不足や二重申請のように現在の状態と衝突するなら409。型は合っているが値が業務ルール上ありえない場合は422。

認可の扱いも決め事が要ります。認証情報が無い、または無効なら401、認証は通っているが権限が足りないなら403。ただしリソースの存在自体を秘匿したい場合は、403ではなく404を返す判断もあります。どちらを採るかを設計書に明記しておかないと、実装者ごとに判断が割れます。

RFC 9457のProblem Detailsで統一するエラー本文の項目設計

エラー本文の形式には、RFC 9457「Problem Details for HTTP APIs」（2023年7月発行・RFC 7807を廃止）という標準があります。メディアタイプは application/problem+json。type（問題種別を示すURI参照）、title（種別の短い説明）、status（HTTPステータスコード）、detail（この発生に固有の説明）、instance（発生箇所を示すURI参照）の5メンバが基本形です。拡張メンバの追加も明記されているため、バリデーション違反の項目一覧などは独自キーで足せます。エラーコードの付番体系や再試行可否の伝え方といった、運用へ載せる側の設計はAPIエラーレスポンス設計とは？コード体系・リトライ判断・漏洩防止の実装手順で扱っています。

この標準を採る利点は2つあります。クライアント側のライブラリが解釈できること、typeのURIをドキュメントページへ向ければエラーコード表を別途配布せずに済むこと。detailには開発者向けの説明を入れ、画面表示の文言はtypeを見てクライアント側で決める分担にします。

APIバージョニング方式の選定と後方互換を壊さない変更の判断基準

公開したAPIは必ず変わります。変更をどう吸収するかを、初版のリリース前に決めておきます。

URIパス版・ヘッダ版・クエリ版の比較と運用コストでの選び方

バージョン表明の位置は3通りあります。URIパス（/v1/orders）、カスタムヘッダやAcceptヘッダ、クエリパラメータ。国内外の主要APIで多数派なのはURIパス方式です。ブラウザやcurlでそのまま叩けて、ログを見ればどの版が呼ばれたか一目で分かる点が運用で効きます。

ヘッダ方式はURIがリソースと1対1に保たれる点でRESTの考え方に忠実ですが、検証時に必ずヘッダを添える手間が生じ、キャッシュの分離設定も要ります。クエリ方式は省略時の既定版が曖昧になりやすく、選ぶ理由が薄い方式。社内システム間の連携なら、URIパス方式でメジャー版のみを刻む形（v1・v2）が運用コストと分かりやすさの釣り合いが取れます。

破壊的変更にあたる修正6種の切り分けと非破壊で機能を追加する手順

版を上げる必要があるのは破壊的変更のときだけです。破壊的にあたるのは、レスポンスからのキー削除、キー名の変更、型の変更、必須リクエスト項目の追加、既存項目の意味の変更、エラーコードの意味変更。一方、レスポンスへのキー追加、任意リクエスト項目の追加、新規エンドポイントの追加は非破壊として扱えます。

非破壊で足す前提には、クライアント側の約束も要ります。未知のキーを受け取ってもエラーにしない実装を求める旨を、ドキュメントに明記しておくこと。この一文が無いとキー追加すら破壊的変更になり、版が際限なく増えます。旧版の廃止は告知から停止まで最低3か月といった期限を決め、Sunsetヘッダで伝えます。

認証・認可とレート制限の方式選定と設計段階で固めておく適用範囲

認証方式は、守る対象と呼び出し主体が決まってから選びます。リソース定義を終えた段階で着手するのは、この依存関係があるためです。

OAuth 2.0とAPIキーの使い分け：公開範囲で決める認証方式

呼び出し主体がサーバ同士で権限がシステム単位に閉じるなら、APIキーまたはクライアント資格情報グラントで足ります。エンドユーザーの代理としてアクセスするなら、OAuth 2.0（RFC 6749）とBearerトークン（RFC 6750）の組み合わせが基本形。ユーザーごとの同意と権限範囲を扱う必要があるかが分岐点です。

OAuth 2.1は2026年9月時点でまだInternet-Draft段階です（draft-ietf-oauth-v2-1-15・2026年3月2日版、IESGへの提出は2026年12月予定）。現行のRFC群を土台にしつつ、暗黙的グラントを使わない、PKCEを前提にするという2.1の方針だけ先取りしておくと、標準化後の移行負担が軽くなります。トークンの有効期限やスコープの粒度は方式より先に決める設計事項。スコープを機能単位で細かく切りすぎると、同意画面が読めなくなります。方式ごとの適用条件と、トークン寿命・検証を実行する層・監査ログまで含めた選定の判断はAPI認証の設計｜方式選定マトリクスとトークン寿命・監査ログの決め方で扱っています。

レート制限の設計：429応答とRetry-Afterで返す情報の粒度

レート制限は、超過時の返し方まで含めて設計対象です。超過時のステータスコードは429（RFC 6585で定義）を使い、Retry-Afterヘッダで再試行までの秒数を返します。この2つが揃っていないと、クライアント側は固定間隔でリトライするしかなく、復旧を遅らせる原因になります。

制限値そのものは運用開始後の調整対象です。初版では「認証済みクライアントごとに毎分いくつ」という単位だけ決め、閾値は実測で動かせる形に。残量をヘッダで返すかは判断が分かれるところで、社内利用のみなら監視ダッシュボードで足ります。

過剰設計になるAPI設計の条件と、工程を打ち切ってよい判断ライン

設計の密度は、APIの公開範囲と寿命で決まります。すべてに同じ密度を求めると、社内の小規模な連携が進みません。

社内向けAPIで設計を薄くしてよい条件と、外部公開との線引き

次の3条件をすべて満たす社内APIは、設計を薄くして構いません。呼び出し元が自社管理下のシステムだけ、クライアント側の改修を同一チームまたは同一発注枠で行える、想定寿命が数年で刷新前提。この場合はOpenAPI定義とエラー形式の統一だけ守り、Sunsetヘッダによる廃止告知や細かなスコープ設計は見送ります。

社外のパートナーが1社でも呼ぶ、あるいは課金対象になるなら密度を上げる側へ振ります。変更のたびに相手の開発計画を止めてしまうからです。「そのうち外部にも公開するかもしれない」という将来観測だけで密度を上げるのは過剰投資。公開が決まった時点でv2として作り直すほうが安く済みます。

HATEOASやGraphQL移行を見送るべき場面と判断の根拠

RESTの成熟度モデルで最上位に置かれるHATEOAS（レスポンスに次の操作リンクを埋め込む方式）は、社内APIでは見送って差し支えありません。クライアントがリンクを辿って動作を決める実装はほとんど書かれず、URLをハードコードした実装が残るためです。実装コストに対して得られるものが釣り合いません。

GraphQLへの移行も条件を切ります。画面ごとに必要な項目が大きく異なり、クライアントが複数種類あり、過剰取得がすでに性能問題として観測されているなら移行に価値があります。逆にクライアントが1つ、エンドポイントが数十本、レスポンスサイズが問題になっていない段階では、移行はスキーマ管理とキャッシュ設計の負担を増やすだけ。REST側の設計を整えるほうが先です。

外部委託でのAPI設計成果物と受け入れレビューで確認する観点

API設計を外部に委託する場合、成果物の定義が曖昧なまま進むと受け入れ時に判断できません。何を受け取るかを契約段階で固定します。

外部委託で受け取るAPI設計の成果物4点と受け入れ時の確認項目

受け取る成果物は4点に絞れます。OpenAPI定義ファイル、エラー種別の一覧（typeのURIと意味の対応表）、認証方式と権限マトリクス、バージョニングと廃止のポリシー。この4点があれば、クライアント側の実装を別ベンダーが担当しても着手できます。画面遷移図やDB設計書は別工程の成果物です。

レビューでは、命名の一貫性、エラー形式の統一、ページネーションの有無、必須項目の妥当性の4点を機械的に見ます。API開発とシステム連携の設計から実装までを外部に任せる場合の進め方はAPI開発・システム連携のページで整理しているため、体制の検討材料として参照してください。

API設計レビューで差し戻す3つの兆候と規則から直す修正の進め方

差し戻し判断の兆候は3つあります。1つ目、URIに動詞が混ざっている（/getOrderList のような形）。設計者がRPC発想のまま書いた合図で、周辺のエンドポイントも同じ癖を持ちます。2つ目、同じ概念に複数の名前が付いている。顧客がcustomerとclientで混在していれば、リソース定義の工程を踏んでいません。

3つ目が、エラー応答の例がドキュメントに1つも載っていない場合。正常系だけのAPI定義は、実装段階でエラー形式が実装者任せになります。修正は個別指摘を並べる形ではなく、命名規則とエラー形式の2つを先に合意し、その規則で全体を通す形が早い。指摘票を100件返すより、規則を2つ渡すほうが収束します。

よくある質問

API設計の進め方について、検討段階で寄せられる質問をまとめます。

API設計とREST APIの設計は同じ意味ですか？

同じではありません。API設計はインターフェースを決める工程全般で、REST以外にGraphQL・gRPC・SOAPも対象に含みます。RESTはHTTPの仕組みに沿ってリソースを操作するアーキテクチャスタイルという位置づけ。国内の実務では「API設計」がREST前提で語られる場面が大半のため、初回の打ち合わせで方式を明示しておくと認識のずれを防げます。

API設計書にはどこまで書けばよいですか？

OpenAPI定義、エラー種別の一覧、認証方式と権限マトリクス、バージョニング方針の4点が最小構成です。各エンドポイントにリクエストとレスポンスの実例JSONを1組ずつ添えると、クライアント側の着手が早まります。テーブル定義や内部処理フローは実装側の文書へ。クライアントから観測できない情報は、レビューの焦点をぼかします。

URIに動詞を使ってはいけない理由は何ですか？

操作の種類はHTTPメソッドで表現するため、URIに動詞を入れると同じ意味が二重になるからです。/getOrders と /orders のGETが併存すると、クライアント側はどちらを使うか判断できません。動詞を許せば語彙が増え続け、/orders/search・/orders/fetch のような重複エンドポイントも生まれます。

APIのバージョンはいつ上げるべきですか？

破壊的変更を入れるときだけです。レスポンスからのキー削除、キー名や型の変更、必須リクエスト項目の追加、既存項目の意味変更が該当します。キー追加や新規エンドポイントの追加は非破壊として同じ版に載せて構いません。版を細かく刻むとサポート対象が増えるため、旧版の廃止時期を告知する仕組みを先に用意するほうが効きます。

小規模な社内APIでもOpenAPI定義は必要ですか？

エンドポイントが5本を超えるなら書く価値があります。定義ファイルからモックサーバとクライアントコードを生成でき、仕様の伝達コストが下がるためです。3本程度で寿命も短いなら、実例をREADMEに貼るだけでも実務は回ります。判断軸は本数より呼び出し側の数で、呼ぶチームが2つ以上あるなら定義ファイルを用意してください。