Format de requête et de réponse de l'API RESTful

Format JSON

Les API RESTful modernes utilisent principalement le format JSON (JavaScript Object Notation) pour transmettre des données.

JSON est comme un « langage universel » pour les données, simple et lisible.

Syntaxe de base de JSON

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

Format de requête

Exemple de requête GET :

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

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

Exemple de requête 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": "用户创建成功"
}

Conception de la structure de réponse

Format de réponse unifié

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

Format de réponse d'erreur

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

Réponse de pagination

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

Champs d'en-tête de requête courants

Nom du champ Objectif Exemple
Content-Type Format des données du corps de requête application/json
Accept Format de réponse attendu application/json
Authorization Informations d'authentification Bearer token123
User-Agent Informations client MyApp/1.0
Autres extensions