SuperAPI AI Directory

request-response

Coding & development

View repository

Updated 10-16 08:49

About this skill

Request and Response Structures

Applicable Scenarios

  • Request field design for endpoints
  • Response field definitions
  • Writing validation rules
  • Field naming conventions

Core Principles

1. 字段稳定性
   公开字段一旦发布不能轻易改语义
   能扩展,不能删

2. 字段含义清晰
   命名见名知意,不需要查文档
  1. Consistent naming Use the same style across the entire API (snake_case or camelCase)

  2. Do not return sensitive information by default Password hashes, internal IDs, and debug information are not returned by default


## 请求结构

### Path 参数(资源标识)

```text
GET /users/{user_id}/orders/{order_id}

- user_id: string (UUID)
- order_id: string (UUID)

Query Parameters (filtering/pagination/options)

GET /users?page=1&page_size=20&status=active&sort=-created_at

- page: integer, default=1
- page_size: integer, default=20, max=100
- status: enum [active, inactive, banned]
- sort: string, prefix - means desc
- keyword: string, optional

Header (cross-cutting information)

Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json
Idempotency-Key: <uuid>      # POST 时
X-Request-Id: <trace-id>     # 追踪
If-Match: "<etag>"           # 并发控制
Accept-Language: zh-CN

Body (creating/modifying data)

POST /users
Content-Type: application/json

{
  "email": "user@example.com",
  "name": "张三",
  "phone": "+8613800138000",
  "metadata": {
    "source": "web"
  }
}

Validation Rules

Each field must define:

- 类型(string / integer / boolean / array / object)
- 必填 / 可选
- 长度限制(min/max)
- 范围限制(min/max for numbers)
- 格式(email / url / uuid / date / regex)
- 枚举值
- 默认值(如有)
- 跨字段规则(如 password === password_confirm)

OpenAPI Validation Example

properties:
  email:
    type: string
    format: email
    minLength: 5
    maxLength: 100
    required: true
  age:
    type: integer
    minimum: 0
    maximum: 150
    required: false
  status:
    type: string
    enum: [active, inactive, banned]
    default: active
  tags:
    type: array
    items:
      type: string
    minItems: 0
    maxItems: 10
    uniqueItems: true

Response Structure

Single Resource Response

{
  "id": "usr_abc123",
  "email": "user@example.com",
  "name": "张三",
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:30:00Z"
}

List Response (recommended structure)

{
  "data": [
    { "id": "usr_001", "name": "张三" },
    { "id": "usr_002", "name": "李四" }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 156,
    "total_pages": 8
  }
}

Nested Relationships (avoid excessive nesting)

{
  "id": "ord_001",
  "user": {
    "id": "usr_123",
    "name": "张三"
  },
  "items": [
    { "id": "itm_001", "product_id": "prd_a", "quantity": 2 }
  ],
  "total": 199.50,
  "status": "paid"
}

Do not exceed 3 levels of nesting; for anything deeper, use an ID + a separate GET.

Field Naming Conventions

风格选一种坚持:
  snake_case:created_at, user_id, total_amount(推荐,可读性强)
  camelCase:createdAt, userId, totalAmount

ID 字段:
  - 前缀化:usr_abc123 / ord_xyz789(Stripe 风格)
  - 或纯 UUID:550e8400-e29b-41d4-a716-446655440000

时间字段:
  - 永远 ISO 8601 + UTC:2026-01-15T10:30:00Z
  - 不要 Unix 时间戳(除非性能极致需求)
  - 不要本地时间(时区混乱)

布尔字段:
  - is_active / has_subscription(is/has 前缀)
  - 不要 active = 1(混淆类型)

枚举:
  - 字符串:status: "active"
  - 不要数字:status: 1

Field Stability Strategy

新增字段(兼容):
  - 客户端忽略未知字段
  - 老客户端不受影响

删除字段(不兼容):
  - 必须升级版本
  - 不能直接删

改字段类型(不兼容):
  - 必须升级版本

改字段语义(不兼容):
  - 必须升级版本
  - 即使字段名不变

废弃字段:
  - 在响应中保留但标注 deprecated
  - 提供新字段
  - 在 OpenAPI 文档标注

Output Format

## 请求响应:POST /users

### 请求

**Headers**:

Authorization: Bearer Content-Type: application/json Idempotency-Key:


**Body**:
```json
{
  "email": "user@example.com",
  "name": "张三",
  "phone": "+8613800138000"
}

Field Definitions:

Field Type Required Validation Description
email string ✅ email format, max 100 Email
name string ✅ 1~50 chars Name
phone string ❌ E.164 format Phone number

Response (success 201)

{
  "id": "usr_abc123",
  "email": "user@example.com",
  "name": "张三",
  "phone": "+8613800138000",
  "status": "active",
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:30:00Z"
}

Field Descriptions:

Field Type Description
id string User ID (usr_ prefix)
status enum active / inactive / banned
created_at ISO 8601 UTC time

## 工作流程

```text
1. 读取端点清单(来自 endpoint-design)
2. 对每个端点定义请求结构
3. 定义所有字段的类型 / 校验
4. 定义响应结构(成功 + 失败)
5. 检查字段命名一致性
6. 检查时间格式 / 布尔 / 枚举规范
7. 输出请求响应说明

Quality Self-Check

□ 字段命名风格一致(不混用 snake/camel)
□ 时间字段 ISO 8601 + UTC
□ 布尔用 true/false 不用 1/0
□ 枚举用字符串不用数字
□ 必填字段标注清楚
□ 校验规则完整(类型/长度/范围/格式)
□ 响应不返回敏感字段(密码哈希等)
□ 列表响应有分页信息
□ 嵌套不超过 3 层

Common Pitfalls

  1. Mixed naming——createdAt and created_at appear at the same time
  2. Inconsistent time formats——some are Unix timestamps, some are ISO 8601
  3. Booleans using 1/0——increases client parsing cost
  4. Returning only id after POST——forces the frontend to GET again
  5. List without total——the frontend cannot paginate precisely
  6. Sensitive field leakage——password_hash is in the response
  7. Field names are not self-explanatory——data1 / val / field2
  8. Excessive nesting——5 levels of nesting, difficult for the frontend to parse

Supporting Templates

  • templates/request-response-template.md — Request structure + response structure + validation rules template

Collaboration with Other Skills

上游:
  endpoint-design → 提供端点清单
  resource-modeling → 提供资源结构

平行:
  error-handling → 错误响应结构
  pagination-filtering → 列表响应结构

下游:
  openapi-mock → 写入 OpenAPI Schema

Related References

  • references/request-response-guide.md — Naming styles, field type conventions, standard fields, unified list/error structures, field stability, optional fields vs null, validation rules, examples from major companies (Stripe Charge / GitHub Issue)