[章番号]: RESTful API仕様書

このテンプレートの使い方

このファイルは、RESTful APIなど、プロジェクトが外部に公開するAPIの仕様を定義するためのテンプレートです。 詳しい使い方は「設計仕様の書き方ガイド」を参照してください。

1. はじめに

1.1. 目的

1.2. 対象読者

2. 基本情報

項目	内容
ベースURL (Production)	https://api.example.com/v1
ベースURL (Staging)	https://staging.api.example.com/v1
認証方式	[例: OAuth 2.0 Bearer トークン] (詳細はAPI設計共通ガイドラインを参照)
データ形式	application/json (UTF-8)

3. エンドポイント一覧

HTTPメソッド	パス	説明
GET	/users	ユーザーの一覧を取得する
POST	/users	新しいユーザーを作成する
GET	/users/{userId}	特定のユーザーの情報を取得する
PUT	/users/{userId}	特定のユーザーの情報を更新する
DELETE	/users/{userId}	特定のユーザーを削除する

---

4. エンドポイント詳細

4.1. ユーザー一覧の取得

• HTTPメソッド: GET
• パス: /users
• 概要: 登録されているユーザーの一覧をページネーション形式で取得する。

クエリパラメータ

パラメータ名	型	必須	説明
limit	integer	No	1ページあたりの取得件数。デフォルトは20。最大100。
offset	integer	No	取得開始位置のオフセット。デフォルトは0。

成功レスポンス

• ステータスコード: 200 OK
• レスポンスボディ:

{
    "total": 120,
    "users": [
        {
            "id": "user-001",
            "name": "Taro Yamada",
            "createdAt": "2025-07-28T10:00:00Z"
        },
        {
            "id": "user-002",
            "name": "Hanako Sato",
            "createdAt": "2025-07-28T11:00:00Z"
        }
    ]
}

エラーレスポンス

• ステータスコード: 400 Bad Request (不正なパラメータ)
• ステータスコード: 401 Unauthorized (認証エラー)

---

4.2. 新しいユーザーの作成

• HTTPメソッド: POST
• パス: /users
• 概要: 新しいユーザーを登録する。

リクエストボディ

{
    "name": "Jiro Suzuki",
    "email": "jiro@example.com"
}

フィールド名	型	必須	説明
name	string	Yes	ユーザー名。
email	string	Yes	メールアドレス。一意である必要があります。

成功レスポンス

• ステータスコード: 201 Created
• レスポンスボディ:

{
    "id": "user-003",
    "name": "Jiro Suzuki",
    "createdAt": "2025-07-28T12:00:00Z"
}

エラーレスポンス

• ステータスコード: 400 Bad Request (必須フィールド欠けなど)
• ステータスコード: 409 Conflict (メールアドレスが既に存在)
• ステータスコード: 401 Unauthorized (認証エラー)

---

5. 共通データモデル

Userオブジェクト

フィールド名	型	説明
id	string	ユーザーの一意なID。
name	string	ユーザー名。
createdAt	string	作成日時 (ISO 8601形式)。

6. 共通エラーレスポンス形式

{
    "error": {
        "code": "INVALID_PARAMETER",
        "message": "The 'limit' parameter must be between 1 and 100."
    }
}