API設計書テンプレート（Markdown）| LAZY DOCS

メソッド	パス	概要
GET	`/items`

メソッド

パス

概要

GET

/items

HTTPステータス	発生条件
400
401
500

HTTPステータス

発生条件

400

401

500

# API設計書 - API名: - 作成日: YYYY/MM/DD - 作成者: ## 1. 共通仕様 - ベースURL: - 認証方式: - データ形式: JSON（UTF-8） ## 2. API一覧 | メソッド | パス | 概要 | | --- | --- | --- | | GET | `/items` | | ## 3. リクエスト / レスポンス ```json { "id": "item_001" } ``` ## 4. エラー | HTTPステータス | 発生条件 | | --- | --- | | 400 | | | 401 | | | 500 | |

API設計書

文書管理情報

項目	内容
システム名
API名
版数	1.0
作成日	YYYY/MM/DD
作成者

改版履歴

版数	日付	変更箇所	変更内容	変更者
1.0	YYYY/MM/DD	-	初版作成

1. 概要

目的:
利用者（呼び出し元）:
OpenAPI 定義ファイル:

2. 共通仕様

項目	仕様
ベースURL	`https://api.example.com/v1`
プロトコル	HTTPS（TLS 1.2 以上）
認証方式	OAuth 2.0 Bearer トークン
データ形式	JSON（UTF-8）
日時形式	ISO 8601（例: `2026-04-01T09:00:00+09:00`）
バージョニング	URL パス（`/v1`）
ページング	`limit` / `cursor`
レート制限
エラー形式	RFC 9457 Problem Details

3. API一覧

API ID	メソッド	パス	概要	認証
API-001	GET	`/items`	一覧取得	要
API-002	POST	`/items`	登録	要

4. API詳細

API-001 一覧取得

メソッド / パス: GET /items
概要:
権限:

リクエストパラメータ

名前	位置	型	必須	説明	例
limit	query	integer	-	取得件数（1〜100、既定 20）	20
cursor	query	string	-	次ページの取得位置

レスポンス（200 OK）

{
  "items": [
    {
      "id": "item_001",
      "name": "sample",
      "createdAt": "2026-04-01T09:00:00+09:00"
    }
  ],
  "nextCursor": null
}

項目	型	必須	説明
items[].id	string	○
items[].name	string	○
nextCursor	string / null	○	次ページがない場合は null

5. エラー仕様

{
  "type": "https://api.example.com/problems/validation-error",
  "title": "入力値が不正です",
  "status": 400,
  "detail": "name は必須です",
  "instance": "/items"
}

HTTPステータス	発生条件	type
400 Bad Request	入力値の形式エラー	validation-error
401 Unauthorized	認証情報がない・無効	unauthorized
403 Forbidden	権限がない	forbidden
404 Not Found	対象が存在しない	not-found
409 Conflict	状態の競合	conflict
429 Too Many Requests	レート制限超過	rate-limited
500 Internal Server Error	サーバー内部エラー	internal-error

6. 備考

項目

内容

システム名

API名

版数

1.0

作成日

YYYY/MM/DD

最終更新日

YYYY/MM/DD

作成者

承認者

版数

日付

変更箇所

変更内容

変更者

1.0

YYYY/MM/DD

初版作成

項目	仕様
ベースURL（本番）	`https://api.example.com/v1`
ベースURL（検証）	`https://api.stg.example.com/v1`
プロトコル	HTTPS（TLS 1.2 以上）
認証方式	OAuth 2.0 Bearer トークン
トークン有効期限
データ形式	JSON（UTF-8）
日時形式	ISO 8601（例: `2026-04-01T09:00:00+09:00`）
命名規則	JSON のキーは lowerCamelCase
バージョニング	URL パス（`/v1`）。後方互換のない変更でメジャー番号を上げる
ページング	`limit` / `cursor`
レート制限
冪等性	POST は `Idempotency-Key` ヘッダーで重複実行を防ぐ
エラー形式	RFC 9457 Problem Details

項目

仕様

ベースURL（本番）

https://api.example.com/v1

ベースURL（検証）

https://api.stg.example.com/v1

プロトコル

HTTPS（TLS 1.2 以上）

認証方式

OAuth 2.0 Bearer トークン

トークン有効期限

データ形式

JSON（UTF-8）

日時形式

ISO 8601（例: 2026-04-01T09:00:00+09:00）

命名規則

JSON のキーは lowerCamelCase

バージョニング

URL パス（/v1）。後方互換のない変更でメジャー番号を上げる

ページング

limit / cursor

レート制限

冪等性

POST は Idempotency-Key ヘッダーで重複実行を防ぐ

エラー形式

RFC 9457 Problem Details

ヘッダー	必須	説明
Authorization	○	`Bearer {token}`
Content-Type	更新系	`application/json`
Idempotency-Key	POST	重複実行防止用の一意な値
X-Request-Id	-	呼び出し元の追跡用 ID

ヘッダー

必須

説明

Authorization

○

Bearer {token}

Content-Type

更新系

application/json

Idempotency-Key

POST

重複実行防止用の一意な値

X-Request-Id

呼び出し元の追跡用 ID

ヘッダー	説明
X-Request-Id	リクエストの追跡用 ID
RateLimit-Remaining	残りリクエスト数

ヘッダー

説明

X-Request-Id

リクエストの追跡用 ID

RateLimit-Remaining

残りリクエスト数

API ID	メソッド	パス	概要	認証	権限（スコープ）
API-001	GET	`/items`	一覧取得	要	`items:read`
API-002	GET	`/items/{id}`	詳細取得	要	`items:read`
API-003	POST	`/items`	登録	要	`items:write`
API-004	PATCH	`/items/{id}`	更新	要	`items:write`
API-005	DELETE	`/items/{id}`	削除	要	`items:write`

API ID

メソッド

パス

概要

認証

権限（スコープ）

API-001

GET

/items

一覧取得

要

items:read

API-002

GET

/items/{id}

詳細取得

要

items:read

API-003

POST

/items

登録

要

items:write

API-004

PATCH

/items/{id}

更新

要

items:write

API-005

DELETE

/items/{id}

削除

要

items:write

項目	型	必須	制約	説明
name	string	○	1〜100 文字
category	string	-	列挙値: `general` / `special`

項目

型

必須

制約

説明

name

string

○

1〜100 文字

category

string

列挙値: general / special

項目	型	必須	説明
id	string	○
createdAt	string	○	ISO 8601

項目

型

必須

説明

string

○

createdAt

string

○

ISO 8601

HTTPステータス	type	発生条件
400	validation-error
409	conflict

HTTPステータス

type

発生条件

400

validation-error

409

conflict

{ "type": "https://api.example.com/problems/validation-error", "title": "入力値が不正です", "status": 400, "detail": "name は必須です", "instance": "/items", "errors": [ { "field": "name", "reason": "required" } ] }

HTTPステータス	発生条件	type	リトライ可否
400 Bad Request	入力値の形式エラー	validation-error	不可
401 Unauthorized	認証情報がない・無効	unauthorized	トークン再取得後に可
403 Forbidden	権限がない	forbidden	不可
404 Not Found	対象が存在しない	not-found	不可
409 Conflict	状態の競合	conflict	状態確認後に可
429 Too Many Requests	レート制限超過	rate-limited	`Retry-After` 後に可
500 Internal Server Error	サーバー内部エラー	internal-error	可（指数バックオフ）
503 Service Unavailable	メンテナンス・過負荷	unavailable	`Retry-After` 後に可

HTTPステータス

発生条件

type

リトライ可否

400 Bad Request

入力値の形式エラー

validation-error

不可

401 Unauthorized

認証情報がない・無効

unauthorized

トークン再取得後に可

403 Forbidden

権限がない

forbidden

不可

404 Not Found

対象が存在しない

not-found

不可

409 Conflict

状態の競合

conflict

状態確認後に可

429 Too Many Requests

レート制限超過

rate-limited

Retry-After 後に可

500 Internal Server Error

サーバー内部エラー

internal-error

可（指数バックオフ）

503 Service Unavailable

メンテナンス・過負荷

unavailable

Retry-After 後に可

項目	目標
応答時間（95 パーセンタイル）
スループット
可用性
タイムアウト（呼び出し元推奨値）

項目

目標

応答時間（95 パーセンタイル）

スループット

可用性

タイムアウト（呼び出し元推奨値）

# API設計書  ## 文書管理情報 | 項目 | 内容 | | --- | --- | | システム名 | | | API名 | | | 版数 | 1.0 | | 作成日 | YYYY/MM/DD | | 最終更新日 | YYYY/MM/DD | | 作成者 | | | 承認者 | | ## 改版履歴 | 版数 | 日付 | 変更箇所 | 変更内容 | 変更者 | | --- | --- | --- | --- | --- | | 1.0 | YYYY/MM/DD | - | 初版作成 | | ## 1. 概要 - 目的: - 利用者（呼び出し元システム）: - 提供範囲（社内 / パートナー / 一般公開）: - OpenAPI 定義ファイル: - 関連する要件・機能ID: ## 2. 共通仕様 | 項目 | 仕様 | | --- | --- | | ベースURL（本番） | `https://api.example.com/v1` | | ベースURL（検証） | `https://api.stg.example.com/v1` | | プロトコル | HTTPS（TLS 1.2 以上） | | 認証方式 | OAuth 2.0 Bearer トークン | | トークン有効期限 | | | データ形式 | JSON（UTF-8） | | 日時形式 | ISO 8601（例: `2026-04-01T09:00:00+09:00`） | | 命名規則 | JSON のキーは lowerCamelCase | | バージョニング | URL パス（`/v1`）。後方互換のない変更でメジャー番号を上げる | | ページング | `limit` / `cursor` | | レート制限 | | | 冪等性 | POST は `Idempotency-Key` ヘッダーで重複実行を防ぐ | | エラー形式 | RFC 9457 Problem Details | ### 2.1 共通リクエストヘッダー | ヘッダー | 必須 | 説明 | | --- | --- | --- | | Authorization | ○ | `Bearer {token}` | | Content-Type | 更新系 | `application/json` | | Idempotency-Key | POST | 重複実行防止用の一意な値 | | X-Request-Id | - | 呼び出し元の追跡用 ID | ### 2.2 共通レスポンスヘッダー | ヘッダー | 説明 | | --- | --- | | X-Request-Id | リクエストの追跡用 ID | | RateLimit-Remaining | 残りリクエスト数 | ## 3. API一覧 | API ID | メソッド | パス | 概要 | 認証 | 権限（スコープ） | | --- | --- | --- | --- | --- | --- | | API-001 | GET | `/items` | 一覧取得 | 要 | `items:read` | | API-002 | GET | `/items/{id}` | 詳細取得 | 要 | `items:read` | | API-003 | POST | `/items` | 登録 | 要 | `items:write` | | API-004 | PATCH | `/items/{id}` | 更新 | 要 | `items:write` | | API-005 | DELETE | `/items/{id}` | 削除 | 要 | `items:write` | ## 4. API詳細 ### API-003 登録 - メソッド / パス: `POST /items` - 概要: - 権限: `items:write` - 冪等性: `Idempotency-Key` 必須 #### リクエストボディ ```json { "name": "sample", "category": "general" } ``` | 項目 | 型 | 必須 | 制約 | 説明 | | --- | --- | --- | --- | --- | | name | string | ○ | 1〜100 文字 | | | category | string | - | 列挙値: `general` / `special` | | #### レスポンス（201 Created） ```json { "id": "item_001", "name": "sample", "category": "general", "createdAt": "2026-04-01T09:00:00+09:00" } ``` | 項目 | 型 | 必須 | 説明 | | --- | --- | --- | --- | | id | string | ○ | | | createdAt | string | ○ | ISO 8601 | #### 処理概要 1. 入力値を検証する 2. 3. #### エラー | HTTPステータス | type | 発生条件 | | --- | --- | --- | | 400 | validation-error | | | 409 | conflict | | ## 5. エラー仕様 ```json { "type": "https://api.example.com/problems/validation-error", "title": "入力値が不正です", "status": 400, "detail": "name は必須です", "instance": "/items", "errors": [ { "field": "name", "reason": "required" } ] } ``` | HTTPステータス | 発生条件 | type | リトライ可否 | | --- | --- | --- | --- | | 400 Bad Request | 入力値の形式エラー | validation-error | 不可 | | 401 Unauthorized | 認証情報がない・無効 | unauthorized | トークン再取得後に可 | | 403 Forbidden | 権限がない | forbidden | 不可 | | 404 Not Found | 対象が存在しない | not-found | 不可 | | 409 Conflict | 状態の競合 | conflict | 状態確認後に可 | | 429 Too Many Requests | レート制限超過 | rate-limited | `Retry-After` 後に可 | | 500 Internal Server Error | サーバー内部エラー | internal-error | 可（指数バックオフ） | | 503 Service Unavailable | メンテナンス・過負荷 | unavailable | `Retry-After` 後に可 | ## 6. 非機能 | 項目 | 目標 | | --- | --- | | 応答時間（95 パーセンタイル） | | | スループット | | | 可用性 | | | タイムアウト（呼び出し元推奨値） | | ## 7. セキュリティ - [ ] すべての通信が HTTPS - [ ] 入力値をサーバー側で検証している - [ ] 他者のリソースを ID 指定で参照できない（認可チェック） - [ ] エラー応答に内部情報（スタックトレースなど）を含めない - [ ] アクセスログに個人情報・トークンを出力しない ## 8. 変更・廃止ポリシー - 後方互換のある変更（項目追加など）: - 後方互換のない変更の告知期間: - 廃止時の告知方法（`Deprecation` / `Sunset` ヘッダーなど）: ## 9. レビュー観点 - [ ] すべての API に正常系と異常系のレスポンスが定義されている - [ ] 権限（スコープ）が API ごとに明確 - [ ] 日時・金額・ID の形式が共通仕様と一致している - [ ] OpenAPI 定義と本書の内容が一致している

API設計書の書き方

用途

API の共通仕様と個別仕様をまとめ、提供側と利用側が実装前に入出力とエラーの扱いを合意するための文書です。OpenAPI 定義と併用します。

主な構成

共通仕様（認証・形式・日時・ページング）
API 一覧
リクエストパラメータ
レスポンス例と項目定義
エラー仕様（RFC 9457）
非機能・セキュリティ（詳細版）

記入のポイント

日時・ID・金額の形式は共通仕様で一度だけ決める
エラーは HTTP ステータスと業務上の理由（type）を分ける
レスポンス例は実際に返る JSON をそのまま載せる
権限のない他者のデータを取得できないか（認可）を必ず確認する

テンプレート本文

API設計書

1. 共通仕様

2. API一覧

3. リクエスト / レスポンス

4. エラー

API設計書

文書管理情報

改版履歴

1. 概要

2. 共通仕様

3. API一覧

4. API詳細

API-001 一覧取得

リクエストパラメータ

レスポンス（200 OK）

5. エラー仕様

6. 備考

API設計書

文書管理情報

改版履歴

1. 概要

2. 共通仕様

2.1 共通リクエストヘッダー

2.2 共通レスポンスヘッダー

3. API一覧

4. API詳細

API-003 登録

リクエストボディ

レスポンス（201 Created）

処理概要

エラー

5. エラー仕様

6. 非機能

7. セキュリティ

8. 変更・廃止ポリシー

9. レビュー観点

API設計書の書き方

用途

主な構成

記入のポイント

準拠・参考

関連記事

設計書（システム）のほかのテンプレート

要件定義書

画面設計書

DB設計書