Формат запросов и ответов RESTful API

Формат JSON

Современные RESTful API в основном используют формат JSON (JavaScript Object Notation) для передачи данных.

JSON — это как «универсальный язык» для данных, простой и удобочитаемый.

Базовый синтаксис JSON

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

Формат запроса

Пример GET-запроса:

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

// 响应
{
  "id": 123,
  "name": "张三",
  "email": "zhangsan@example.com",
  "createdAt": "2024-01-15T08:30:00Z"
}

Пример POST-запроса:

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

{
  "name": "李四",
  "email": "lisi@example.com",
  "password": "securePassword123"
}

// 响应
{
  "id": 124,
  "name": "李四",
  "email": "lisi@example.com",
  "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
Другие расширения