RESTful API リクエストとレスポンス形式

JSON 形式

現代の RESTful API は主に JSON（JavaScript Object Notation）形式を使用してデータを転送します。

JSON はデータの「共通言語」のようなもので、シンプルで読みやすいです。

JSON 基本構文

{
  "name": "张三",
  "age": 25,
  "email": "[email protected]",
  "hobbies": ["阅读", "游泳", "编程"],
  "address": {
    "city": "北京",
    "district": "朝阳区"
  },
  "isActive": true
}

リクエスト形式

GET リクエスト例:

// 请求
GET /api/users/123
Accept: application/json

// 响应
{
  "id": 123,
  "name": "张三",
  "email": "[email protected]",
  "createdAt": "2024-01-15T08:30:00Z"
}

POST リクエスト例:

// 请求
POST /api/users
Content-Type: application/json

{
  "name": "李四",
  "email": "[email protected]",
  "password": "securePassword123"
}

// 响应
{
  "id": 124,
  "name": "李四",
  "email": "[email protected]",
  "createdAt": "2024-01-15T09:00:00Z",
  "message": "用户创建成功"
}

---

レスポンス構造設計

統一されたレスポンス形式

{
  "success": true,
  "data": {
    "id": 123,
    "name": "张三"
  },
  "message": "操作成功",
  "timestamp": "2024-01-15T08:30:00Z"
}

エラーレスポンス形式

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "输入数据验证失败",
    "details": [
      {
        "field": "email",
        "message": "邮箱格式不正确"
      }
    ]
  },
  "timestamp": "2024-01-15T08:30:00Z"
}

ページネーションレスポンス

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "用户1"
    },
    {
      "id": 2,
      "name": "用户2"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 10,
    "totalItems": 100,
    "itemsPerPage": 10
  }
}

リクエストヘッダーの一般的なフィールド

フィールド名	用途	例
Content-Type	リクエストボディのデータ形式	application/json
Accept	期待されるレスポンス形式	application/json
Authorization	認証情報	Bearer token123
User-Agent	クライアント情報	MyApp/1.0

その他の拡張