【テンプレあり】英語API仕様書の書き方｜ITプロジェクトで使える日英フォーマット付き

英語でAPI仕様書を書くよう求められたとき、どのセクションを入れればいいか迷った経験はないだろうか。

API仕様書はチーム間・システム間の認識齟齬を防ぐ重要なドキュメントだ。グローバルチームでは英語が基本になるが、構成さえ押さえれば英語でも問題なく書ける。

この記事では、API仕様書に必要な7つの構成要素と、そのまま使える日英テンプレートを紹介する。コピペして使えばすぐに実務で活用できる。

API仕様書に必要な7つの構成要素
1. なぜ英語で書くのか
2. OpenAPIとの使い分け
テンプレートをダウンロード（Word）
日本語版テンプレート（コピペOK）
英語版テンプレート（コピペOK）
各セクションの書き方と例文
API仕様書でよく使う英語表現
まとめ：英語API仕様書は7つのセクションで完成する

API仕様書に必要な7つの構成要素

API仕様書はAPIの呼び出し方を定義するドキュメントだ。以下の7つが標準的な構成要素になる。

基本情報（Document Info）
概要（Overview）
認証（Authentication）
ベースURL（Base URL）
エンドポイント一覧（Endpoints）
リクエスト・レスポンス仕様（Request / Response）
エラーコード（Error Codes）

なぜ英語で書くのか

グローバルチームやOSSプロジェクトでは英語が共通言語になる。英語で書くことで、海外チームや外部パートナーとの認識合わせがスムーズになる。

レビューや引き継ぎのときに「この項目は何を意味するか」という質問が減り、ドキュメントとして自走できる状態を作れる。

OpenAPIとの使い分け

OpenAPI（Swagger）で自動生成するプロジェクトも多い。ただし、「なぜこの設計にしたか」「認証の取得手順」「エラー時の対処方針」といった設計思想は自動生成では補えない。

このテンプレートはOpenAPIの補完ドキュメントとして、または小規模プロジェクトのスタンドアロン仕様書として使える。

テンプレートをダウンロード（Word）

以下のWordファイルをダウンロードして、プロジェクトに合わせてカスタマイズして使ってほしい。表の列・行はそのまま追加・削除できる。

📥 日本語テンプレートをダウンロード（Word）
📥 Download English Template (Word)

日本語版テンプレート（コピペOK）

基本情報

項目	内容
API名	（API名を記入）
バージョン	v1.0
作成日	YYYY-MM-DD
作成者	（名前）
最終更新日	YYYY-MM-DD
ステータス	Draft / In Review / Approved

概要

項目	内容
目的	（このAPIが何をするかを1〜2文で記入）
対象ユーザー	（呼び出し元のシステム・チームを記入）
前提条件	（利用に必要な前提・依存システムを記入）
制約事項	（レート制限・利用時間帯など）

認証

項目	内容
認証方式	Bearer Token / API Key / OAuth 2.0 など
ヘッダー名	Authorization
形式	Bearer {token}
トークン取得方法	（取得手順のURLまたは手順を記入）
トークン有効期限	（例：24時間）

ベースURL

環境	URL
本番	https://api.example.com/v1
ステージング	https://staging-api.example.com/v1
開発	https://dev-api.example.com/v1

エンドポイント一覧

メソッド	パス	説明
GET	/users	ユーザー一覧を取得
GET	/users/{id}	指定ユーザーの詳細を取得
POST	/users	新規ユーザーを作成
PUT	/users/{id}	指定ユーザーの情報を更新
DELETE	/users/{id}	指定ユーザーを削除

リクエスト仕様（例：POST /users）

パラメータ名	型	必須	説明
name	string	○	ユーザー名（最大50文字）
email	string	○	メールアドレス
role	string	×	ロール（admin / user、デフォルト: user）

レスポンス仕様（例：POST /users 成功時 200 OK）

フィールド名	型	説明
id	string	生成されたユーザーID
name	string	ユーザー名
email	string	メールアドレス
role	string	ロール
created_at	string	作成日時（ISO 8601形式）

エラーコード

コード	メッセージ	説明	対処方法
400	Bad Request	リクエストパラメータが不正	パラメータを確認する
401	Unauthorized	認証に失敗した	トークンを再取得する
403	Forbidden	アクセス権限がない	権限の付与を依頼する
404	Not Found	リソースが存在しない	IDを確認する
429	Too Many Requests	レート制限に達した	時間をおいて再実行する
500	Internal Server Error	サーバー側のエラー	管理者に連絡する

英語版テンプレート（コピペOK）

Document Info

Field	Value
API Name	(Enter API name)
Version	v1.0
Created Date	YYYY-MM-DD
Author	(Name)
Last Updated	YYYY-MM-DD
Status	Draft / In Review / Approved

Overview

Field	Value
Purpose	(Describe what this API does in 1–2 sentences)
Target Users	(Enter the calling systems or teams)
Prerequisites	(Enter required preconditions or dependencies)
Constraints	(e.g., rate limits, maintenance windows)

Authentication

Field	Value
Method	Bearer Token / API Key / OAuth 2.0
Header Name	Authorization
Format	Bearer {token}
How to Obtain Token	(Enter URL or steps to obtain a token)
Token Expiry	(e.g., 24 hours)

Base URL

Environment	URL
Production	https://api.example.com/v1
Staging	https://staging-api.example.com/v1
Development	https://dev-api.example.com/v1

Endpoints

Method	Path	Description
GET	/users	Retrieve a list of users
GET	/users/{id}	Retrieve details of a specific user
POST	/users	Create a new user
PUT	/users/{id}	Update information of a specific user
DELETE	/users/{id}	Delete a specific user

Request Specification (Example: POST /users)

Parameter	Type	Required	Description
name	string	Yes	User name (max 50 characters)
email	string	Yes	Email address
role	string	No	Role (admin / user; default: user)

Response Specification (Example: POST /users — 200 OK)

Field	Type	Description
id	string	Generated user ID
name	string	User name
email	string	Email address
role	string	Role
created_at	string	Creation timestamp (ISO 8601)

Error Codes

Code	Message	Description	Action
400	Bad Request	Invalid request parameters	Check request parameters
401	Unauthorized	Authentication failed	Re-obtain the token
403	Forbidden	Insufficient permissions	Request permission from admin
404	Not Found	Resource does not exist	Verify the resource ID
429	Too Many Requests	Rate limit exceeded	Wait and retry
500	Internal Server Error	Server-side error	Contact the API owner

各セクションの書き方と例文

テンプレートを埋めるときに悩みやすいセクションを解説する。

Overview（概要）の書き方

目的は「このAPIが何をするか」を1〜2文で説明する。動詞から始めて簡潔に書くのがポイントだ。

日本語	英語
ユーザー情報の取得・作成・更新・削除を行うAPIです	This API provides endpoints to retrieve, create, update, and delete user information.
在庫データをリアルタイムで外部システムに提供します	This API exposes real-time inventory data to external systems.
注文処理フローを自動化するためのAPIです	This API automates the order processing workflow.

Authentication（認証）の書き方

認証方式と取得方法を具体的に書く。「どこでトークンを取得するか」が書かれていないと呼び出し側が詰まる。

日本語	英語
すべてのリクエストにBearerトークンが必要です	All requests require a valid Bearer token in the Authorization header.
トークンはPOST /auth/tokenで取得できます	Obtain a token by calling POST /auth/token with valid credentials.
トークンの有効期限は24時間です	Tokens expire after 24 hours and must be refreshed.

Error Codes（エラーコード）の書き方

エラーコードには「対処方法」を必ず記載する。呼び出し側がエラーを受け取ったときに自己解決できるドキュメントが理想だ。

日本語	英語
必須パラメータが不足しています	Required parameter is missing.
このリソースへのアクセス権限がありません	You do not have permission to access this resource.
レート制限に達しました。60秒後に再試行してください	Rate limit exceeded. Please retry after 60 seconds.

英語でのAPI設計議論をさらに深めたい方は、エンジニアの英語API設計議論術も参考にしてほしい。

API仕様書でよく使う英語表現

実務でよく使う英語表現を場面別にまとめた。

リクエスト・レスポンス説明

日本語	英語
必須パラメータ	Required parameter
任意パラメータ	Optional parameter
リクエストボディ	Request body
レスポンスボディ	Response body
クエリパラメータ	Query parameter
パスパラメータ	Path parameter
ページネーション	Pagination
最大件数	Maximum number of items

型・フォーマット

日本語	英語
文字列	string
整数	integer
真偽値	boolean
配列	array
オブジェクト	object
日時（ISO 8601形式）	datetime (ISO 8601 format)
UUIDv4形式	UUIDv4 format

状態・制約

日本語	英語
読み取り専用	Read-only
書き込み専用	Write-only
廃止予定	Deprecated
後方互換性を維持	Backward compatible
レート制限：100回/分	Rate limit: 100 requests per minute
最大ペイロードサイズ	Maximum payload size