api-contract-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

API Design Patterns

API设计模式

A comprehensive skill for designing, documenting, and implementing APIs that developers love to use. Covers REST, GraphQL, and hybrid approaches with emphasis on consistency, discoverability, and maintainability.

这是一套全面的技能指南，用于设计、文档化和实现开发者乐于使用的API。涵盖REST、GraphQL及混合方案，重点强调一致性、可发现性和可维护性。

When to Use

适用场景

Designing new REST or GraphQL APIs from scratch
Reviewing existing API contracts for consistency and best practices
Evaluating API technologies and frameworks
Implementing API versioning strategies
Designing authentication and authorization flows
Creating OpenAPI/Swagger specifications
Building developer-friendly API documentation

从零开始设计全新的REST或GraphQL API
评审现有API契约的一致性与最佳实践
评估API技术与框架
实现API版本控制策略
设计认证与授权流程
创建OpenAPI/Swagger规范
构建对开发者友好的API文档

Core Principles

核心原则

1. Contract-First Design

1. 契约优先设计

Define the API contract before implementation. This enables parallel development, clearer communication, and better documentation.

DESIGN SEQUENCE:
1. IDENTIFY use cases and consumer needs
2. MODEL resources and their relationships
3. DEFINE operations (CRUD + custom actions)
4. SPECIFY request/response schemas
5. DOCUMENT error scenarios
6. VALIDATE with consumers before implementing

在实现前定义API契约。这支持并行开发、更清晰的沟通以及更完善的文档。

DESIGN SEQUENCE:
1. IDENTIFY use cases and consumer needs
2. MODEL resources and their relationships
3. DEFINE operations (CRUD + custom actions)
4. SPECIFY request/response schemas
5. DOCUMENT error scenarios
6. VALIDATE with consumers before implementing

2. Consistency Over Cleverness

2. 一致性优先于技巧性

APIs should be predictable. Developers should be able to guess how an endpoint works based on patterns established elsewhere in the API.

CONSISTENCY CHECKLIST:
- Naming conventions (plural nouns, kebab-case)
- Response envelope structure
- Error format across all endpoints
- Pagination approach
- Query parameter patterns
- Date/time formatting (ISO 8601)

API应具备可预测性。开发者应能根据API中其他地方建立的模式，推断出某个端点的工作方式。

CONSISTENCY CHECKLIST:
- Naming conventions (plural nouns, kebab-case)
- Response envelope structure
- Error format across all endpoints
- Pagination approach
- Query parameter patterns
- Date/time formatting (ISO 8601)

3. Design for Evolution

3. 为演进而设计

APIs must evolve without breaking existing consumers. Plan for change from day one.

EVOLUTION STRATEGIES:
- Additive changes only (new fields, endpoints)
- Deprecation with sunset periods
- Version negotiation (headers, URL paths)
- Backward compatibility testing

API必须能够演进且不影响现有使用者。从第一天起就为变化做好规划。

EVOLUTION STRATEGIES:
- Additive changes only (new fields, endpoints)
- Deprecation with sunset periods
- Version negotiation (headers, URL paths)
- Backward compatibility testing

REST API Patterns

REST API模式

Resource Modeling

资源建模

Resources represent business entities. URLs should reflect the resource hierarchy.

GOOD:
GET    /users                    # List users
POST   /users                    # Create user
GET    /users/{id}               # Get user
PATCH  /users/{id}               # Partial update
DELETE /users/{id}               # Delete user
GET    /users/{id}/orders        # User's orders (sub-resource)

AVOID:
GET    /getUsers                 # Verbs in URLs
POST   /createNewUser            # Redundant verbs
GET    /user-list                # Inconsistent naming
POST   /users/{id}/delete        # Wrong HTTP method

资源代表业务实体。URL应反映资源的层级结构。

GOOD:
GET    /users                    # 列出用户
POST   /users                    # 创建用户
GET    /users/{id}               # 获取单个用户
PATCH  /users/{id}               # 部分更新
DELETE /users/{id}               # 删除用户
GET    /users/{id}/orders        # 用户的订单（子资源）

AVOID:
GET    /getUsers                 # URL中使用动词
POST   /createNewUser            # 冗余动词
GET    /user-list                # 命名不一致
POST   /users/{id}/delete        # 使用错误的HTTP方法

HTTP Method Semantics

HTTP方法语义

Method	Usage	Idempotent	Safe
GET	Retrieve resource(s)	Yes	Yes
POST	Create resource, trigger action	No	No
PUT	Replace entire resource	Yes	No
PATCH	Partial update	Yes	No
DELETE	Remove resource	Yes	No
OPTIONS	CORS preflight, capability discovery	Yes	Yes

方法	用途	幂等性	安全性
GET	检索资源	是	是
POST	创建资源、触发操作	否	否
PUT	替换整个资源	是	否
PATCH	部分更新	是	否
DELETE	删除资源	是	否
OPTIONS	CORS预检查、能力发现	是	是

Status Code Selection

状态码选择

SUCCESS:
200 OK           - Successful GET, PUT, PATCH, DELETE
201 Created      - Successful POST (include Location header)
202 Accepted     - Async operation started
204 No Content   - Success with no response body

CLIENT ERRORS:
400 Bad Request  - Malformed request, validation failure
401 Unauthorized - Missing or invalid authentication
403 Forbidden    - Authenticated but not authorized
404 Not Found    - Resource doesn't exist
409 Conflict     - State conflict (duplicate, version mismatch)
422 Unprocessable- Semantically invalid (business rule violation)
429 Too Many     - Rate limit exceeded

SERVER ERRORS:
500 Internal     - Unexpected server error
502 Bad Gateway  - Upstream service failure
503 Unavailable  - Temporary overload or maintenance
504 Gateway Timeout - Upstream timeout

SUCCESS:
200 OK           - GET、PUT、PATCH、DELETE请求成功
201 Created      - POST请求成功（需包含Location头）
202 Accepted     - 异步操作已启动
204 No Content   - 请求成功但无响应体

CLIENT ERRORS:
400 Bad Request  - 请求格式错误、验证失败
401 Unauthorized - 缺少或无效的认证信息
403 Forbidden    - 已认证但无权限
404 Not Found    - 资源不存在
409 Conflict     - 状态冲突（重复、版本不匹配）
422 Unprocessable- 语义无效（违反业务规则）
429 Too Many     - 超出请求频率限制

SERVER ERRORS:
500 Internal     - 服务器意外错误
502 Bad Gateway  - 上游服务故障
503 Unavailable  - 服务器临时过载或维护中
504 Gateway Timeout - 上游服务超时

Error Response Format

错误响应格式

Standardize error responses across all endpoints:

json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "code": "INVALID_FORMAT",
        "message": "Email must be a valid email address"
      }
    ],
    "requestId": "req_abc123",
    "timestamp": "2025-01-15T10:30:00Z",
    "documentation": "https://api.example.com/docs/errors#VALIDATION_ERROR"
  }
}

在所有端点中标准化错误响应：

json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "code": "INVALID_FORMAT",
        "message": "Email must be a valid email address"
      }
    ],
    "requestId": "req_abc123",
    "timestamp": "2025-01-15T10:30:00Z",
    "documentation": "https://api.example.com/docs/errors#VALIDATION_ERROR"
  }
}

Pagination Patterns

分页模式

Offset-Based (Simple, not for large datasets)

基于偏移量（简单，但不适用于大数据集）

GET /users?offset=20&limit=10

Response:
{
  "data": [...],
  "pagination": {
    "total": 150,
    "offset": 20,
    "limit": 10,
    "hasMore": true
  }
}

GET /users?offset=20&limit=10

Response:
{
  "data": [...],
  "pagination": {
    "total": 150,
    "offset": 20,
    "limit": 10,
    "hasMore": true
  }
}

Cursor-Based (Recommended for large datasets)

基于游标（推荐用于大数据集）

GET /users?cursor=eyJpZCI6MTAwfQ&limit=10

Response:
{
  "data": [...],
  "pagination": {
    "nextCursor": "eyJpZCI6MTEwfQ",
    "prevCursor": "eyJpZCI6OTB9",
    "hasMore": true
  }
}

GET /users?cursor=eyJpZCI6MTAwfQ&limit=10

Response:
{
  "data": [...],
  "pagination": {
    "nextCursor": "eyJpZCI6MTEwfQ",
    "prevCursor": "eyJpZCI6OTB9",
    "hasMore": true
  }
}

Filtering and Sorting

过滤与排序

FILTERING:
GET /users?status=active                    # Exact match
GET /users?created_after=2025-01-01         # Date range
GET /users?role=admin,moderator             # Multiple values
GET /users?search=john                      # Full-text search

SORTING:
GET /users?sort=created_at                  # Ascending (default)
GET /users?sort=-created_at                 # Descending (prefix -)
GET /users?sort=status,-created_at          # Multiple fields

FIELD SELECTION:
GET /users?fields=id,name,email             # Sparse fieldsets
GET /users?expand=organization              # Include related

FILTERING:
GET /users?status=active                    # 精确匹配
GET /users?created_after=2025-01-01         # 日期范围
GET /users?role=admin,moderator             # 多值匹配
GET /users?search=john                      # 全文搜索

SORTING:
GET /users?sort=created_at                  # 升序（默认）
GET /users?sort=-created_at                 # 降序（前缀-）
GET /users?sort=status,-created_at          # 多字段排序

FIELD SELECTION:
GET /users?fields=id,name,email             # 稀疏字段集
GET /users?expand=organization              # 包含关联资源

GraphQL Patterns

GraphQL模式

Schema Design Principles

Schema设计原则

graphql

undefined

graphql

undefined

Use clear, descriptive type names

type User { id: ID! email: String! displayName: String! createdAt: DateTime!

Relationships with clear naming

organization: Organization orders(first: Int, after: String): OrderConnection! }

type User { id: ID! email: String! displayName: String! createdAt: DateTime!

Relationships with clear naming

organization: Organization orders(first: Int, after: String): OrderConnection! }

Use connections for paginated lists

type OrderConnection { edges: [OrderEdge!]! pageInfo: PageInfo! totalCount: Int! }

type OrderEdge { node: Order! cursor: String! }

type PageInfo { hasNextPage: Boolean! hasPreviousPage: Boolean! startCursor: String endCursor: String }

undefined

type OrderConnection { edges: [OrderEdge!]! pageInfo: PageInfo! totalCount: Int! }

type OrderEdge { node: Order! cursor: String! }

type PageInfo { hasNextPage: Boolean! hasPreviousPage: Boolean! startCursor: String endCursor: String }

undefined

Query Design

查询设计

graphql

type Query {
  # Single resource by ID
  user(id: ID!): User

  # List with filtering and pagination
  users(
    filter: UserFilter
    first: Int
    after: String
    orderBy: UserOrderBy
  ): UserConnection!

  # Viewer pattern for current user
  viewer: User
}

input UserFilter {
  status: UserStatus
  organizationId: ID
  searchQuery: String
}

enum UserOrderBy {
  CREATED_AT_ASC
  CREATED_AT_DESC
  NAME_ASC
  NAME_DESC
}

graphql

type Query {
  # Single resource by ID
  user(id: ID!): User

  # List with filtering and pagination
  users(
    filter: UserFilter
    first: Int
    after: String
    orderBy: UserOrderBy
  ): UserConnection!

  # Viewer pattern for current user
  viewer: User
}

input UserFilter {
  status: UserStatus
  organizationId: ID
  searchQuery: String
}

enum UserOrderBy {
  CREATED_AT_ASC
  CREATED_AT_DESC
  NAME_ASC
  NAME_DESC
}

Mutation Design

变更设计

graphql

type Mutation {
  # Use input types for complex mutations
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(input: UpdateUserInput!): UpdateUserPayload!
  deleteUser(id: ID!): DeleteUserPayload!
}

input CreateUserInput {
  email: String!
  displayName: String!
  organizationId: ID
}

graphql

type Mutation {
  # Use input types for complex mutations
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(input: UpdateUserInput!): UpdateUserPayload!
  deleteUser(id: ID!): DeleteUserPayload!
}

input CreateUserInput {
  email: String!
  displayName: String!
  organizationId: ID
}

Payload types for consistent responses

type CreateUserPayload { user: User errors: [UserError!]! }

type UserError { field: String code: String! message: String! }

undefined

type CreateUserPayload { user: User errors: [UserError!]! }

type UserError { field: String code: String! message: String! }

undefined

N+1 Query Prevention

N+1查询预防

STRATEGIES:
1. DataLoader pattern for batching
2. Query complexity analysis and limits
3. Depth limiting
4. Field-level cost calculation
5. Persisted queries for production

STRATEGIES:
1. DataLoader pattern for batching
2. Query complexity analysis and limits
3. Depth limiting
4. Field-level cost calculation
5. Persisted queries for production

API Versioning Strategies

API版本控制策略

URL Path Versioning

URL路径版本控制

GET /v1/users
GET /v2/users

PROS:
- Explicit and visible
- Easy to route in infrastructure
- Clear in logs and monitoring

CONS:
- URL pollution
- Harder to deprecate gracefully

GET /v1/users
GET /v2/users

PROS:
- 明确且可见
- 基础设施中易于路由
- 日志和监控中清晰可辨

CONS:
- URL冗余
- 难以优雅地弃用旧版本

Header Versioning

请求头版本控制

GET /users
Accept: application/vnd.api+json; version=2

PROS:
- Clean URLs
- Content negotiation friendly
- Easier partial versioning

CONS:
- Less visible
- Harder to test in browser

GET /users
Accept: application/vnd.api+json; version=2

PROS:
- URL简洁
- 符合内容协商机制
- 更易于实现部分版本控制

CONS:
- 可见性较低
- 浏览器中测试较困难

Query Parameter Versioning

查询参数版本控制

GET /users?api-version=2025-01-15

PROS:
- Easy to test
- Visible in URLs
- Date-based versions are intuitive

CONS:
- Clutters query strings
- Easy to forget

GET /users?api-version=2025-01-15

PROS:
- 测试便捷
- URL中可见
- 基于日期的版本号直观易懂

CONS:
- 使查询字符串杂乱
- 容易被遗忘

Recommended: Dual Approach

推荐：双重方案

1. Major versions in URL path: /v1/, /v2/
2. Minor versions via header: API-Version: 2025-01-15
3. Default to latest minor within major
4. Sunset headers for deprecation warnings

1. 主版本号放在URL路径中：/v1/, /v2/
2. 次版本号通过请求头传递：API-Version: 2025-01-15
3. 主版本内默认使用最新次版本
4. 使用Sunset头提示弃用警告

Authentication Patterns

认证模式

API Keys

API密钥

USAGE: Server-to-server, rate limiting, analytics
TRANSPORT: Header (Authorization: ApiKey xxx) or query param

SECURITY:
- Rotate keys regularly
- Different keys for environments
- Scope keys to specific operations
- Never expose in client-side code

USAGE: Server-to-server, rate limiting, analytics
TRANSPORT: Header (Authorization: ApiKey xxx) or query param

SECURITY:
- 定期轮换密钥
- 为不同环境使用不同密钥
- 为密钥分配特定操作权限
- 绝不在客户端代码中暴露密钥

OAuth 2.0 / OIDC

FLOWS:
- Authorization Code + PKCE: Web apps, mobile apps
- Client Credentials: Server-to-server
- Device Code: CLI tools, smart TVs

TOKEN HANDLING:
- Short-lived access tokens (15-60 min)
- Refresh tokens for session extension
- Token introspection for validation
- Token revocation endpoint

FLOWS:
- Authorization Code + PKCE: Web apps, mobile apps
- Client Credentials: Server-to-server
- Device Code: CLI tools, smart TVs

TOKEN HANDLING:
- 短生命周期访问令牌（15-60分钟）
- 使用刷新令牌延长会话
- 令牌 introspection 验证
- 令牌撤销端点

JWT Best Practices

JWT最佳实践

CLAIMS:
{
  "iss": "https://auth.example.com",
  "sub": "user_123",
  "aud": "api.example.com",
  "exp": 1705320000,
  "iat": 1705316400,
  "scope": "read:users write:users"
}

SECURITY:
- Use asymmetric keys (RS256, ES256)
- Validate all claims
- Check token expiration
- Verify audience matches
- Keep tokens stateless when possible

CLAIMS:
{
  "iss": "https://auth.example.com",
  "sub": "user_123",
  "aud": "api.example.com",
  "exp": 1705320000,
  "iat": 1705316400,
  "scope": "read:users write:users"
}

SECURITY:
- 使用非对称密钥（RS256, ES256）
- 验证所有声明
- 检查令牌过期时间
- 验证受众匹配
- 尽可能保持令牌无状态

OpenAPI/Swagger Patterns

OpenAPI/Swagger模式

Specification Structure

规范结构

yaml

openapi: 3.1.0
info:
  title: Example API
  version: 1.0.0
  description: API description with markdown support
  contact:
    name: API Support
    url: https://example.com/support

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://api.staging.example.com/v1
    description: Staging

security:
  - bearerAuth: []

paths:
  /users:
    get:
      operationId: listUsers
      summary: List all users
      tags: [Users]
      # ... operation details

components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email

yaml

openapi: 3.1.0
info:
  title: Example API
  version: 1.0.0
  description: API description with markdown support
  contact:
    name: API Support
    url: https://example.com/support

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://api.staging.example.com/v1
    description: Staging

security:
  - bearerAuth: []

paths:
  /users:
    get:
      operationId: listUsers
      summary: List all users
      tags: [Users]
      # ... operation details

components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email

Reusable Components

可复用组件

yaml

components:
  schemas:
    # Reusable pagination
    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
        page:
          type: integer
        perPage:
          type: integer

    # Reusable error
    Error:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
        message:
          type: string

  parameters:
    # Reusable query params
    PageParam:
      name: page
      in: query
      schema:
        type: integer
        default: 1
        minimum: 1

  responses:
    # Reusable responses
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

yaml

components:
  schemas:
    # Reusable pagination
    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
        page:
          type: integer
        perPage:
          type: integer

    # Reusable error
    Error:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
        message:
          type: string

  parameters:
    # Reusable query params
    PageParam:
      name: page
      in: query
      schema:
        type: integer
        default: 1
        minimum: 1

  responses:
    # Reusable responses
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

Best Practices

最佳实践

Do

建议

Design APIs for consumers, not implementation convenience
Use meaningful HTTP status codes
Provide idempotency keys for non-idempotent operations
Include rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining)
Return Location header for created resources
Support CORS properly for browser clients
Document all error codes with resolution steps
Version your API from day one
Use HTTPS exclusively
Implement request validation with clear error messages

为API使用者设计，而非为实现便捷
使用有意义的HTTP状态码
为非幂等操作提供幂等键
包含频率限制头（X-RateLimit-Limit, X-RateLimit-Remaining）
为创建的资源返回Location头
为浏览器客户端正确支持CORS
记录所有错误码及解决步骤
从第一天起就为API添加版本控制
仅使用HTTPS
实现请求验证并返回清晰的错误信息

Avoid

避免

Exposing internal implementation details (database IDs, stack traces)
Breaking changes without versioning
Inconsistent naming across endpoints
Deeply nested URLs (more than 2 levels)
Using GET for operations with side effects
Returning different structures for success/error
Ignoring backward compatibility
Over-fetching in GraphQL without limits
Authentication via query parameters (except OAuth callbacks)
Mixing REST and RPC styles in the same API

暴露内部实现细节（数据库ID、堆栈跟踪）
不进行版本控制就引入破坏性变更
端点间命名不一致
过深的嵌套URL（超过2层）
使用GET执行有副作用的操作
成功/错误返回不同的结构
忽略向后兼容性
GraphQL中不设限制导致过度获取
通过查询参数进行认证（OAuth回调除外）
在同一API中混合REST和RPC风格

References

参考资料

```
templates/rest-api-template.md
```
- REST API specification template
```
templates/graphql-schema-template.md
```
- GraphQL schema template

```
templates/rest-api-template.md
```
- REST API规范模板
```
templates/graphql-schema-template.md
```
- GraphQL Schema模板