Formato de solicitud y respuesta de API RESTful

Formato JSON

Las API RESTful modernas utilizan principalmente el formato JSON (JavaScript Object Notation) para transmitir datos.

JSON es como el "lenguaje universal" de los datos: simple y fácil de leer.

Sintaxis básica de JSON

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

Formato de solicitud

Ejemplo de solicitud GET:

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

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

Ejemplo de solicitud 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": "用户创建成功"
}

---

Diseño de la estructura de respuesta

Formato de respuesta unificado

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

Formato de respuesta de error

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

Respuesta paginada

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

Campos comunes del encabezado de solicitud

Nombre del campo	Función	Ejemplo
Content-Type	Formato de datos del cuerpo de la solicitud	application/json
Accept	Formato de respuesta esperado	application/json
Authorization	Información de autenticación	Bearer token123
User-Agent	Información del cliente	MyApp/1.0

Otras extensiones