API仕様書テンプレート

活用プロンプト例

エージェント：ドキュメントエージェント

@会員情報更新画面仕様の画面設計書を参考に、APIを設計し、 @API仕様書テンプレートの様式に沿って出力して。

</aside>

テンプレート

API仕様書テンプレート.md

# API仕様書

## 1. 概要

### 1.1 目的
[APIの目的と主な機能について簡潔に説明してください]

### 1.2 対象ユーザー
[このAPIが想定するユーザー層や利用シーンについて説明してください]

### 1.3 技術仕様
- **API形式**: [REST, GraphQL, SOAP, gRPC等]
- **データフォーマット**: [JSON, XML, Protocol Buffers等]
- **プロトコル**: [HTTP/HTTPS, WebSocket等]

## 2. 認証とアクセス制御

### 2.1 認証方式
[APIの認証方式について説明してください（API Key, OAuth 2.0, JWT等）]

例: Authorization: Bearer {token}


### 2.2 アクセス権限
[利用可能な権限レベルと各権限での操作範囲について説明してください]

### 2.3 レート制限
| プラン | リクエスト上限 | 期間 |
|--------|----------------|------|
| 無料   | [例: 100]      | [例: 1時間あたり] |
| 有料   | [例: 1000]     | [例: 1時間あたり] |

## 3. エンドポイント情報

### ベースURL

https://api.example.com/v1


### 3.1 リソース: [リソース名]

#### [HTTPメソッド] [パス]
[このエンドポイントの機能説明]

**URL**: `[完全なURLパス]`

## 4. リクエスト仕様

### 4.1 クエリパラメータ
| パラメータ名 | 必須 | 型     | 説明                   | デフォルト値 |
|------------|------|--------|------------------------|------------|
| [param1]   | はい  | string | [パラメータの説明]      | -          |
| [param2]   | いいえ | number | [パラメータの説明]      | [値]       |

### 4.2 リクエストヘッダー
| ヘッダー名          | 必須 | 説明                     |
|-------------------|------|--------------------------|
| Content-Type      | はい  | [例: application/json]   |
| Authorization     | はい  | [認証情報について説明]     |

### 4.3 リクエストボディ
[リクエストのボディ形式について説明してください（該当する場合）]

```json
{
  "property1": "value1",
  "property2": 123,
  "nestedObject": {
    "nestedProperty": "value"
  }
}

プロパティ詳細

プロパティ名	必須	型	説明	制約
property1	はい	string	[説明]	[例: 最大50文字]
property2	いいえ	number	[説明]	[例: 1から100の整数]
nestedObject	いいえ	object	[説明]	-

5. レスポンス仕様

5.1 成功レスポンス

ステータスコード: 200 OK

{
  "status": "success",
  "data": {
    "id": "12345",
    "name": "サンプル名",
    "createdAt": "2023-01-01T12:00:00Z"
  }
}

レスポンスフィールド

フィールド名	型	説明
status	string	リクエスト処理状態
data	object	レスポンスデータオブジェクト
data.id	string	リソースの一意識別子
data.name	string	リソース名
data.createdAt	string	作成日時（ISO 8601形式）

5.2 エラーレスポンス

ステータスコード: [適切なエラーコード（400, 401, 403, 404, 500等）]

{
  "status": "error",
  "code": "ERROR_CODE",
  "message": "エラーメッセージ",
  "details": {
    "field": "エラーが発生したフィールド名",
    "reason": "エラーの詳細な理由"
  }
}

6. エラーハンドリング

6.1 エラーコード一覧

HTTPステータス	エラーコード	説明	対処法
400	INVALID_REQUEST	リクエストパラメータが不正	リクエスト内容を確認してください
401	UNAUTHORIZED	認証に失敗	認証情報を確認してください
403	FORBIDDEN	権限がない	適切な権限を取得してください
404	RESOURCE_NOT_FOUND	リソースが見つからない	IDを確認してください
429	RATE_LIMIT_EXCEEDED	レート制限を超過	リクエスト頻度を下げてください
500	INTERNAL_ERROR	サーバー内部エラー	サポートに連絡してください

7. リソース定義

7.1 [リソース名]

[リソースの概要説明]

プロパティ

プロパティ名	型	説明	例
id	string	リソースの一意識別子	"12345"
name	string	リソースの名前	"サンプル名"
type	enum	リソースのタイプ	"standard", "premium"
createdAt	string	作成日時	"2023-01-01T12:00:00Z"

8. 実装例

8.1 cURL

curl -X GET "<https://api.example.com/v1/resources?param1=value1>" \\
     -H "Authorization: Bearer YOUR_API_TOKEN" \\
     -H "Content-Type: application/json"

8.2 JavaScript (fetch)

fetch('<https://api.example.com/v1/resources?param1=value1>', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

9. バージョン管理

9.1 現在のバージョン

API Version: v1

9.2 変更履歴

バージョン	リリース日	変更内容
v1.0.0	2025-05-01	初期リリース

9.3 非推奨機能

機能	非推奨バージョン	削除予定バージョン	代替手段
`/v1/old-endpoint`	v1.1.0	v2.0.0	`/v1/new-endpoint` を使用

10. 制限事項

10.1 パフォーマンス制限

同時接続数: [例: 100接続/IP]
タイムアウト: [例: 30秒]
最大ペイロードサイズ: [例: 5MB]

10.2 利用条件

[APIの利用条件について説明してください]

10.3 セキュリティ上の注意点

トークンは安全に保管し、公開リポジトリには保存しないでください
HTTPS接続を使用してください
[その他のセキュリティに関する推奨事項]

11. サポート

11.1 連絡先

メール: [email protected]
サポートサイト: https://support.example.com

11.2 ドキュメント

API ドキュメント: https://docs.example.com/api
チュートリアル: https://docs.example.com/tutorials


## アウトプットイメージ

```markdown
# API仕様書

## 1. 概要

### 1.1 目的

会員情報（メールアドレス・パスワード・プロフィール画像）変更のためのAPI群。画面上の「会員情報更新画面」にて入力された情報を安全にサーバへ連携し、更新処理・バリデーション・セッション管理を実現。

### 1.2 対象ユーザー

自分自身の会員情報の変更が可能なログインユーザー。主な利用シーンは本人によるメールアドレス・パスワード・プロフィール画像更新。

### 1.3 技術仕様

- **API形式**: REST
- **データフォーマット**: JSON（画像はMultipart）
- **プロトコル**: HTTPS

## 2. 認証とアクセス制御

### 2.1 認証方式

JWTによる認証
例:
Authorization: Bearer {token}

### 2.2 アクセス権限

ログインユーザーのみ実行可能。
自身の会員情報に対してのみ操作可能。

### 2.3 レート制限

| プラン   | リクエスト上限 | 期間     |
| ----- | ------- | ------ |
| 全ユーザー | 100     | 1時間あたり |

## 3. エンドポイント情報

### ベースURL

https://api.example.com/v1


#### 3.1 メールアドレス変更

- **POST** `/member/email`
- 新しいメールアドレスに更新する

#### 3.2 パスワード変更

- **POST** `/member/password`
- 新しいパスワードへ変更する

#### 3.3 プロフィール画像変更

- **POST** `/member/image`
- 新しい画像をアップロード

## 4. リクエスト仕様

### 4.1 クエリパラメータ

- なし（全てボディ送信）

### 4.2 リクエストヘッダー

| ヘッダー名         | 必須 | 説明                                      |
| ------------- | -- | --------------------------------------- |
| Content-Type  | はい | application/json or multipart/form-data |
| Authorization | はい | Bearerトークン認証                            |

### 4.3 リクエストボディ

#### `/member/email`

```json
{
  "newEmail": "[email protected]"
}

プロパティ名	必須	型	説明	制約
newEmail	はい	string	新メールアドレス	メール形式・ユニーク

`/member/password`

{
  "currentPassword": "currentPass123!",
  "newPassword": "newPass456!",
  "confirmPassword": "newPass456!"
}

プロパティ名	必須	型	説明	制約
currentPassword	はい	string	現在パスワード	必須、正当性
newPassword	はい	string	新しいパスワード	8文字以上、英数字記号混在
confirmPassword	はい	string	新パスワード（確認）	newPasswordと一致

`/member/image`

フォームデータ

項目名	必須	型	説明	制約
profileImage	はい	File	新プロフィール画像	jpg/png, 最大2MB

5. レスポンス仕様

5.1 成功レスポンス

ステータスコード: 200 OK

{
  "status": "success",
  "message": "会員情報を更新しました。"
}

5.2 エラーレスポンス

ステータスコード: 400, 401, 422, 500

{
  "status": "error",
  "code": "VALIDATION_ERROR",
  "message": "入力値が不正です",
  "details": {
    "field": "newEmail",
    "reason": "既に登録済みです。"
  }
}