API仕様書の書き方｜記載項目チェックリストと記入例の粒度

API仕様書に何をどこまで書けば、受け取った側が問い合わせなしに実装へ入れるのか。判断の拠り所になるのが、デジタル庁が2024年9月30日に改定した「APIテクニカルガイドブック」と、IPAが2025年3月26日に初版を出した「API標準設計ガイド・基礎編」です。この2つは記載項目を明示的に列挙している数少ない公的資料でありながら、内容を突き合わせて整理した記事は検索結果にほとんど出てきません。ここでは両ガイドの項目を並べ、テンプレートの限界、エンドポイント1件あたりの記入枠、認証・エラー・利用制限の書式まで、API仕様書の書き方を項目単位で組み立てます。

まとめ：API仕様書に必ず入れる6項目と粒度の決めどころ

デジタル庁のAPIテクニカルガイドブックは、表4-2「公開を推奨するドキュメント」のなかでAPI仕様書に含めるべき項目を6つ挙げています。API機能、API利用方法、エラーコード、リクエスト、レスポンス、提供データに関する説明。この6つが最小セットです。

粒度の判断基準は1つだけ持てば足ります。読み手がその文書だけで最初の1リクエストを送り、返ってきたエラーの意味を自力で説明できるか。ここを満たさない仕様書は、項目が揃っていても問い合わせを生みます。なお両ガイドが参照しているRFCは3本とも現行版に置き換わっているため、記述をそのまま引き写すと古い番号を配ることになります。以降では6項目それぞれの書式を、公的ガイドと実在する行政APIの記述から具体化していきます。

仕様書・設計書・リファレンスの呼び分けと担当範囲

同じ文書が「API仕様書」「API設計書」「API定義書」「APIリファレンス」と呼ばれ、社内で指すものがずれたまま話が進む。呼称を統一するより、担当範囲を先に決めるほうが早く片付きます。

仕様書と設計書が分かれる基準：読み手と確定タイミング

設計書は作る側の内部文書で、実装前に決めるべき事項を並べたもの。仕様書は使う側に配る外部文書で、確定した振る舞いを記述したものです。線引きは絶対ではありません。IPAのAPI標準設計ガイド・基礎編は「API標準設計書」の実体としてOpenAPI Specification（OAS）のYAMLファイルを指しており、同ガイドの表3が示す構成はInfo、Servers、Paths、components、Security、Tags、externalDocsの7セクション。設計書であると同時に、そのまま外部公開できる仕様書でもあります。

分けるかどうかは社外公開の有無で決めてください。社外に配るなら、検討経緯や未確定事項を含む設計書とは別に確定分だけを切り出す。社内の1システム間連携で完結するなら、1つの文書に統合したほうが更新漏れが起きません。リソースの切り方そのものを詰める段階なら、リソース指向でのURI命名と標準メソッドの使い分けを先に固めてから文書化に入ると手戻りが減ります。

リファレンスとの違い：更新責任の所在

APIリファレンスは実装から自動生成できる網羅的な一覧を指すのが一般的です。デジタル庁のガイドも「Swagger UIを利用することで、自動でAPI仕様のドキュメントを生成できます」と書いています。ただし同じガイドの表4-2は、API概要・API仕様書・利用規約・利用申請・利用事例の5種類を別建てで推奨しています。

自動生成が肩代わりできるのはリファレンス部分だけです。各言語のSDKまで機械的に配る段階になればOpenAPI Generatorの対応言語と導入手順が入口になりますが、生成できるのはリファレンスとコードにとどまります。利用申請の手順、利用規約、データの更新タイミングは実装コードのどこにも書かれていないため、ツールを入れても誰かが手で書く。更新責任がツールにあるのか人にあるのかで分けると、呼称の議論はほぼ消えます。

記載項目チェックリスト：仕様書本体の6項目と概要ドキュメントの12項目

API仕様書本体に載せる6項目

右列は補足ではなく、項目を落としたときに返ってくる質問の型です。とくに「提供データに関する説明」は抜けやすく、デジタル庁のガイドはデータ更新日・提供元・データ内容・更新タイミングを挙げ、「特にデータ提供API」と括弧書きを添えて例示しています。夜間バッチで1日1回更新されるデータを利用側がリアルタイム値と誤解したまま実装するのは、典型的な事故です。

概要ドキュメントへ切り出す12項目

• データ内容の概要
• 提供方式
• エンドポイント
• OAS定義ファイルの公開場所
• リクエストフォーマット形式
• レスポンスフォーマット形式
• TLS(SSL)サポート
• 利用申請
• 認証機能
• 利用制限
• 開発者専用サイト
• 利用規約

これはデジタル庁のガイドが「API概要」として別ドキュメント化を推奨している12項目で、仕様書本体に混ぜ込まず、利用者の目に留まりやすい場所に置くよう書かれています。同ガイドの表5-1は内閣府RESAS APIを記入例として示し、利用制限を「呼び出し回数制限あり 上限：2000回/日」、認証機能を「APIキー」、利用規約を「出典明記により、編集・加工も含め自由に利用可」と書いています。「制限あり」で止めず数値まで書く、この粒度が参照する価値のある部分です。ただし同じ表には利用制限の行が2つあり、値も二重に記載されています。項目の並びは真似しても、この重複は持ち込まないでください。

テンプレートとExcel台帳をそのまま使うときの限界

配布されているAPI仕様書テンプレートは、項目の抜け防止には効きます。ただし多くは概要・認証・エンドポイント・リクエスト・レスポンス・エラーで完結しており、デジタル庁の6項目のうち「提供データに関する説明」に相当する枠を持ちません。データ提供系のAPIでここが空欄のまま配られると、更新タイミングの問い合わせが後から一斉に来ます。採用するなら、まず提供データの更新日・提供元・更新頻度の行を足してください。

記述形式はExcelでもMarkdownでも構いません。Excel台帳は一覧性とフィルタが効くため、パラメータ定義のように行数が増える部分に向く反面、差分がレビューしづらく変更履歴がファイル名に埋もれます。Markdownはその逆で、Gitで差分を追えるかわりに横に広い表を書きにくい。項目定義だけをExcelに切り出し、本文はMarkdownで管理する分け方が破綻しにくい選択です。国税庁の法人番号システムWeb-APIも、項目定義にあたる「リソース定義書」だけをPDFとExcelの両形式で別配布しています。

エンドポイント1件あたりの記入枠と繰り返しの型

6項目を揃えても、エンドポイントごとの書式がばらついていると読み手は毎回探し方を変えることになります。実在する行政APIの解説書を見ると、1機能あたりの枠が固定されています。国税庁の法人番号システムWeb-APIの解説書のうち第五編（Ver.3.0）は、機能の概要、リクエストのフォーマット、リクエスト例と応答結果のサンプル、一連番号の設定（ソート順）という4つを検索機能ごとに繰り返し、エラーコード及びHTTPステータスコードは全機能共通の章として末尾に1回だけ置く構成です。共通部分を機能ごとに書かない、という粒度設計がそのまま参考になります。

リクエスト例と応答サンプルを実データで置く理由

GET /api/v1/invoices?updated_since=2026-08-01&limit=50 HTTP/1.1
Host: api.example.com
Authorization: Bearer {access_token}
Accept: application/json

パラメータ表だけを載せてサンプルを省く仕様書は、クエリ文字列の連結方法、日付の書式、認証情報を載せるヘッダ名で必ず質問を呼びます。1リクエストを丸ごと貼れば、それらが同時に確定する。応答側も同様で、フィールド一覧を10行書くより正常時のJSONを1件ぶん実際の値で貼るほうが誤解が減ります。

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "total": 2,
  "next_cursor": "eyJpZCI6MTAyfQ",
  "items": [
    {
      "invoice_id": "INV-000101",
      "issued_at": "2026-08-01T09:30:00+09:00",
      "amount": 132000,
      "currency": "JPY",
      "status": "issued"
    }
  ]
}

この1件で、金額が整数なのか小数なのか、日時にタイムゾーンが付くのか、ページングがカーソル方式なのかが確定します。説明文を増やすより効きます。

パラメータ定義に必要な5列

書式は先に標準を決めておくと表が短くなります。IPAのガイドは項目定義方針として、日時はformat:date-timeでYYYY-MM-DDTHH:mm:ss+09:00の形、所在地コードとしてJIS X 0401/0402、文字コードはUTF-8、値が固定リストならenumで制限する、と採用する標準を先に列挙しています。国税庁の解説書が項目定義を「別紙1 リソース定義書」として本文から独立させているのも同じ発想で、同じ項目が複数エンドポイントに出てくるなら定義は1箇所に集約したほうが保守できます。

認証方式の書き方：APIキー・OAuth 2.0・OpenID Connectの記述差

「認証方式：OAuth 2.0」の一行で終わっている仕様書は、実装者から見て情報量がほぼゼロです。デジタル庁のガイドは「API利用者認証を強く推奨する。少なくともAPIキーによる実装以上の認証レベルを担保すること」としたうえで、APIキーを「コピーされアクセスされる可能性もあるため、強固な対策ではない」と明記し、パラメータにAPIキーを含めないこと、不要となったAPIキーを削除することを求めています。個人認証を正確に行う必要がある際、たとえば行政手続を行う場合や個人情報を扱う場合にはOpenID Connectの認証も行うことを推奨し、極めて守秘性の高い情報についての認証が必要な場合にはそのうちのHybrid Flowを推奨する、というところまで踏み込んでいます。

仕様書側に落とすときは、次の4点を重要度順に書いてください。上の2つが欠けると接続自体ができません。

• 資格情報をどこに載せるか（Authorizationヘッダか独自ヘッダか、クエリ文字列は不可か）
• 資格情報の取得手順、有効期限、再発行の方法
• 認証・認可の失敗時に返すステータス（401と403のどちらをどの条件で返すか）
• スコープや権限の一覧と、エンドポイントごとの必要権限

方式によって書く量は大きく変わります。APIキーなら、載せるヘッダ名と発行・失効の手順でほぼ足ります。OAuth 2.0を採るなら、認可エンドポイントとトークンエンドポイントのURL、採用するグラントタイプ、スコープ名の一覧、アクセストークンの有効期限とリフレッシュトークンの扱いまで書かないと、利用側はトークン取得のコードを書けません。OpenID ConnectはOAuth 2.0の上に載る認証レイヤーなので、そこにIDトークンの検証方法とdiscoveryエンドポイントのURLが加わります。方式名を書き換えるだけでは仕様書が追いつきません。

どの方式でも、資格情報をクエリ文字列に置く仕様は採用しないでください。URLはアクセスログ、プロキシ、Refererに残ります。仕様書に書式を書いた時点で利用側の実装が固定されるため、この一行が後から効いてきます。

エラー仕様の書き方：RFC 9457とステータスコードの割り当て

problem+jsonの5項目と独自拡張

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 60

{
  "type": "https://api.example.com/probs/rate-limit",
  "title": "レート制限を超過しました",
  "status": 429,
  "detail": "1分あたり600回の上限を超えました。60秒後に再試行してください。",
  "instance": "/api/v1/invoices",
  "retry_after_seconds": 60
}

エラー形式を自前で発明する必要はありません。RFC 9457「Problem Details for HTTP APIs」がメディアタイプ application/problem+json と、type、status、title、detail、instanceという5つのメンバを定義しています。独自の情報を足すことも第3.2節で認められており、デジタル庁のガイドが図2-3に載せる残高不足の例では、推奨項目にbalanceとaccountsを追加しています。上の例のretry_after_secondsも同じ拡張です。

typeにはエラー種別ごとのURIを入れ、その参照先に説明ページを用意します。typeメンバを省略した場合の既定値は about:blank だとRFC 9457の第3.1.1節が定めているので、該当URIが無いときは省略するか about:blank を明示してください。空文字やnullで埋めると、利用側のエラーハンドリングが分岐できなくなります。エラー形式をAPI全体で統一する設計そのものについては、Problem Detailsによるエラー形式の統一で扱っています。

公的ガイドが参照するRFCの更新状況

表の3本はデジタル庁のAPIテクニカルガイドブック（2024年9月30日改定）の参考文献一覧に載っているものです。1行目のRFC 7807は、IPAのAPI標準設計ガイド・基礎編（2025年3月26日初版）もエラー形式の準拠先として挙げています。7807は2023年7月にRFC 9457へ置き換わっているため、新規に書く仕様書は9457を引いてください。メンバ名は変わっておらず、参照番号の差し替えだけで済みます。RFC 9110はSTD 97として標準化され、RFC 7231を含む複数のRFCを廃止しました。

ステータスコードの説明文は、公的資料の引き写しではなくRFCから起こしてください。IPAのガイドの表6は429 Too Many Requestsの説明を「サーバ側での処理中にエラーが発生」としており、デジタル庁の表2-2の「クライアントが短時間に多すぎるリクエストを送信した」と食い違います。これは誤植というより表の行構成の問題で、IPAの表6には500 Internal Server Errorの行そのものが無く、レート制限超過は403の説明に入っています。429を定義するのはRFC 6585の第4節、「一定時間に多すぎるリクエストを送った（レート制限）」が正しい定義です。429はRFC 9110に含まれておらず、いまもRFC 6585が根拠。同節はRetry-Afterを含めてもよい（MAY）とする一方、429のレスポンスをキャッシュに保存してはならない（MUST NOT）と定めているため、CDNを前に置く構成では仕様書で明言してください。

利用制限の書き方：標準化前のレート制限ヘッダと明記すべき6点

レート制限の残量を伝えるHTTPヘッダは、2026年8月時点でまだ標準化されていません。IETFで進行中の「RateLimit header fields for HTTP」（draft-ietf-httpapi-ratelimit-headers）は第11版が2026年5月23日に提出された段階のInternet-Draftで、この版の有効期限は2026年11月24日です。RFCにはなっていません。デジタル庁のガイドが表2-3で例示するX-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Resetは、標準ではなくデファクトです。

標準が無い以上、仕様書側で書き切るしかありません。最低限、次の6点を埋めてください。

• ヘッダ名（X-RateLimit-系を使うのか独自名か）
• Resetの単位（残り秒数かUnix時間か。デジタル庁の例は1372700873というUnix時間）
• 集計窓の種類（固定窓か移動窓か）
• 制限の適用単位（APIキー単位、利用者単位、IP単位のいずれか）
• 超過時のステータスコード（429）とRetry-Afterを返すかどうか
• 上限の数値

最後の1点は数字で書いてください。IPAのガイドは「1分間に5000リクエストまで許可する」と例示し、デジタル庁が引くRESAS APIの記入例は「上限：2000回/日」です。「大量アクセスはご遠慮ください」は仕様ではなくお願いで、利用側は再試行間隔を設計できません。

版管理と変更履歴の書き方：分冊の判断基準と変更理由列の置き方

国税庁の法人番号システムWeb-APIは、解説書を6編に分けています。第一編が利用手続（共通編・4.9版・令和7年2月）、第二編が概要編（1.2版・令和3年10月）、第三編から第六編がVer.1.0からVer.4.0までのバージョン別（それぞれ2.4版、2.4版、1.4版、1.2版）。共通部分を第一編と第二編に寄せる構成です。第一編の表1によればVer.1.0の提供開始は2015年12月、Ver.4.0が2019年3月。10年以上前の版が「Ver.1.0～Ver.3.0は、新しいバージョンの提供開始後も引き続きご利用できます」という記述のもと、いまも並行稼働しています。

変更履歴でそのまま真似できるのは、変更内容と変更理由を別の列に分けている点です。第五編（Ver.3.0・1.4版・令和4年4月）の改版履歴は5件あり、1.4版は変更内容が「情報記録媒体によるデータ提供に関する記載を削除」、変更理由が「全件データの情報記録媒体によるデータ提供のサービス終了」と対になっています。理由が併記されていれば、利用側は自分に影響する変更かを1行で判断できます。

分冊のコストも同じ履歴から読み取れます。この改版は同じ文言で第一編の4.6版（令和4年4月）にも入っており、1つの変更を複数の編へ波及させる作業が発生しています。判断は単純です。運用中のバージョンが1つなら分けない。破壊的変更で旧バージョンを残す運用に入った時点で分ける。なお版を残しても通信要件のほうは動きます。同サイトは令和8年5月20日付で「法人番号公表サイト等のサーバ証明書とセキュリティ設定の変更について」を告知し、10月下旬の実施を予定しています。旧版の文書を残すことと旧い通信環境の動作を保証することは別問題だと、仕様書に書き分けてください。

IPAのガイドはinfo.versionにセマンティックバージョニングを使い、CHANGELOG.mdへのリンクをinfo.descriptionかexternalDocsから提供するよう勧めています。バージョンをURIパスに置くかヘッダで指定するかという方式の比較は、API設計ガイドのバージョニング戦略の整理を先に読むと決めやすくなります。

OpenAPIへ機械可読化する判断基準と、文書のまま運用してよい規模

OpenAPI Specificationの最新版は3.2.0と3.1.2で、いずれも2025年9月19日にリリースされました。その前の3.1.1と3.0.4は2024年10月24日で、3.0系の最終パッチが3.0.4です。移行するかどうかは、クライアントSDKを配布する、実装前にモックを立てる、CIで破壊的変更を機械的に検知する、のいずれかに当てはまるかで決めてください。デジタル庁のガイドもOASに基づいてAPIモックを自動生成できるツールの使用を推奨しており、これらを狙うならYAML化の投資は回収できます。

逆に、社内の1システム間連携でエンドポイントが数本、読み手が同じチーム内という規模なら、YAMLに移す必要はありません。実装とYAMLの二重管理になり、片方が更新されなくなった瞬間に仕様書としての信頼が失われます。IPAが事例に取り上げた国税庁の法人番号システムWEB-APIについても、同ガイドは「仕様書はWORD形式のPDFで公開され、API標準設計書の形式では提供されていない」と記しています。ただし前述のとおり、項目定義にあたるリソース定義書だけはExcel形式でも配布されています。機械可読化は文書全体を一度に移す必要はなく、再利用される項目定義から始められます。

移す場合の入口は、記法から入るか、既存の型定義から起こすかで変わります。YAMLやJSONの記法とSwagger UIでの表示はOpenAPIとSwaggerの違いと仕様書の書き方にまとめており、仕様書の自動生成ツールを比較したい場合もそちらが出発点になります。実装側にスキーマ定義があるなら、Zodのスキーマから仕様書を生成する方法のように既存の型定義を出力元にするほうが二重管理を避けられます。

よくある質問

API仕様書とは何ですか？

APIを利用する側に向けて、接続先・認証方法・送るデータ・返るデータ・エラーの意味を、確定した内容で記述した文書です。デジタル庁のAPIテクニカルガイドブックは、含めるべき項目としてAPI機能、API利用方法、エラーコード、リクエスト、レスポンス、提供データに関する説明の6つを挙げています。利用申請の手順や利用規約は別ドキュメント側に整理されており、同ガイドが公開を推奨するドキュメントは全部で5種類です。

API仕様書とAPI設計書は何が違いますか？

読み手と、内容が確定しているかどうかが違います。設計書は作る側の内部文書で未確定事項を含み、仕様書は使う側に配る外部文書で確定した振る舞いだけを載せます。境界は固定ではなく、IPAのAPI標準設計ガイド・基礎編は「API標準設計書」としてOASのYAMLファイルを指しており、両者を兼ねる形です。社外公開があるなら分け、社内完結なら1つにまとめてください。

API仕様書のテンプレートはそのまま使えますか？

項目の抜け防止には有効ですが、そのままでは足りません。配布されているテンプレートの多くは概要・認証・エンドポイント・リクエスト・レスポンス・エラーで構成され、デジタル庁が挙げる6項目のうち「提供データに関する説明」に当たる枠を持ちません。データ提供系のAPIでは、データ更新日・提供元・更新タイミングの行を自分で追加してください。

API仕様書に認証方式はどこまで書けばよいですか？

方式名だけでは足りません。資格情報を載せるヘッダ名、取得手順と有効期限、再発行の方法、認証失敗時に401と403のどちらを返すか、スコープや権限の一覧まで書いて初めて利用側が実装できます。OAuth 2.0を採る場合は認可・トークン両エンドポイントのURL、グラントタイプ、リフレッシュトークンの扱いも必要です。デジタル庁のガイドはAPIキーを「強固な対策ではない」とし、パラメータに含めないよう求めています。

APIのエラーコードは仕様書にどこまで書くべきですか？

HTTPステータスコードと、アプリケーション独自のエラーコードの両方を一覧化してください。国税庁の法人番号システムWeb-APIの解説書は「HTTPステータスコード、エラーコード及びエラーメッセージ一覧」を別紙として独立させています。形式はRFC 9457のproblem detailに合わせ、type、status、title、detail、instanceの5メンバを基本に、必要な情報は独自メンバで追加します。IANAのHTTPステータスコードレジストリでは429の出典がRFC 6585、422がRFC 9110と根拠文書が分かれる点にも注意してください。

API仕様書はOpenAPI（Swagger）で作らないといけませんか？

必須ではありません。クライアントSDKの配布、モックの自動生成、CIでの破壊的変更検知のいずれかを狙うならOASへの機械可読化が有効ですが、エンドポイントが数本で読み手が同一チーム内なら、実装とYAMLの二重管理になるだけです。IPAはガイドの事例に選んだ国税庁の法人番号システムWEB-APIについて「仕様書はWORD形式のPDFで公開され、API標準設計書の形式では提供されていない」と記しています。採用する場合の版は、3.1系なら3.1.2、3.0系なら3.0.4が基準です。

関連記事

• OpenAPIとは｜Swaggerとの違い・仕様書(YAML/JSON)の書き方とSwagger UIをわかりやすく解説
• Google API設計ガイドの概要と良いAPI設計の基本ポイント【完全ガイド序章】
• リソース指向アーキテクチャ(ROA)とは？RESTとの違いとAPI設計への落とし込み方
• OpenAPI Generatorとは｜生成できるもの・仕組み・対応言語と導入方法
• ZodからOpenAPIを生成する方法｜zod-to-openapiとZod 4ネイティブ変換・ライブラリの選び分け