Back to Details

api-contract-sync

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

API Contract Sync Protocol

API契约同步协议

Apidog MCP is the single source of truth for all API contracts in this project. Every agent that implements or consumes an API endpoint MUST verify against Apidog.
Apidog MCP是本项目中所有API契约的单一数据源。所有实现或调用API端点的角色必须依据Apidog进行验证。

Contract Flow

契约流程

Apidog Specification (source of truth)
    │
    ├──→ team-lead: defines shared types/models matching spec
    │
    ├──→ backend-dev: implements endpoints matching spec exactly
    │
    ├──→ web-dev / mobile-dev: consumes endpoints using typed clients
    │
    ├──→ test-worker: validates against spec in tests
    │
    └──→ reviewer: verifies all implementations match spec
Note: For mobile-only projects without a backend (e.g., apps consuming third-party APIs), API contracts are defined by the external API documentation. Use Apidog to document the external API surface your app consumes, or skip this protocol if no API layer exists.
Apidog Specification (source of truth)
    │
    ├──→ team-lead: 定义与规范匹配的共享类型/模型
    │
    ├──→ backend-dev: 严格按照规范实现端点
    │
    ├──→ web-dev / mobile-dev: 使用类型化客户端调用端点
    │
    ├──→ test-worker: 在测试中依据规范进行验证
    │
    └──→ reviewer: 验证所有实现是否符合规范
注意：对于没有后端的纯移动项目（例如调用第三方API的应用），API契约由外部API文档定义。使用Apidog记录你的应用所调用的外部API接口，若不存在API层则可跳过本协议。

For Team Lead

团队负责人指南

Before spawning workers for any API-related feature:
  1. Query Apidog MCP for the relevant endpoint specifications
  2. Create or update shared types/models that match the spec:
    Web/TypeScript Projects:
    • Create interfaces in 
      src/types/
      for request bodies, response types, path/query params
    Flutter/Dart Projects:
    • Create model classes in 
      lib/core/models/
      for request DTOs, response models, enums
    Other Projects:
    • Define types/models in the appropriate shared location for the detected stack
  3. Include the Apidog project reference in each worker's spawn prompt
If the endpoint doesn't exist in Apidog yet:
  1. Define the endpoint specification first
  2. Get it documented in Apidog before spawning workers
  3. Reference the spec in spawn prompts
在为任何API相关功能分配任务前：
  1. 查询Apidog MCP获取相关端点规范
  2. 创建或更新与规范匹配的共享类型/模型：
    Web/TypeScript项目：
    • 在
      src/types/
      目录下创建接口，用于定义请求体、响应类型、路径/查询参数
    Flutter/Dart项目：
    • 在
      lib/core/models/
      目录下创建模型类，用于定义请求DTO、响应模型、枚举
    其他项目：
    • 根据技术栈在合适的共享位置定义类型/模型
  3. 在任务分配提示中包含Apidog项目引用
若端点尚未在Apidog中定义：
  1. 先定义端点规范
  2. 在Apidog中完成文档记录后再分配任务
  3. 在任务分配提示中引用该规范

For Backend Workers

后端开发人员指南

When implementing an API endpoint:
  1. Query Apidog MCP for the endpoint specification before writing code
  2. Match exactly: Your route handler must:
    • Accept the documented request shape
    • Return the documented response shape
    • Handle all documented error codes
  3. Validate input using schemas/validators that match the Apidog spec:
    Web/TypeScript (Zod example):
    typescript
    // Schema must match Apidog spec for the endpoint
const CreateItemSchema = z.object({
  name: z.string().min(1).max(200),
  description: z.string().min(1).max(5000),
});
    Flutter/Dart (freezed/json_serializable example):
    dart
    // Model must match Apidog spec for the endpoint
@freezed
class CreateItemRequest with _$CreateItemRequest {
  factory CreateItemRequest({
    required String name,
    required String description,
  }) = _CreateItemRequest;
  factory CreateItemRequest.fromJson(Map<String, dynamic> json) =>
      _$CreateItemRequestFromJson(json);
}
  4. Return consistent error shapes appropriate to your stack
  5. If you must deviate from the spec, STOP and notify the team-lead
实现API端点时：
  1. 编写代码前先查询Apidog MCP获取端点规范
  2. 严格匹配规范：你的路由处理程序必须：
    • 接收文档中定义的请求结构
    • 返回文档中定义的响应结构
    • 处理所有文档中定义的错误码
  3. 使用与Apidog规范匹配的模式/验证器验证输入：
    Web/TypeScript（Zod示例）：
    typescript
    // Schema must match Apidog spec for the endpoint
const CreateItemSchema = z.object({
  name: z.string().min(1).max(200),
  description: z.string().min(1).max(5000),
});
    Flutter/Dart（freezed/json_serializable示例）：
    dart
    // Model must match Apidog spec for the endpoint
@freezed
class CreateItemRequest with _$CreateItemRequest {
  factory CreateItemRequest({
    required String name,
    required String description,
  }) = _CreateItemRequest;
  factory CreateItemRequest.fromJson(Map<String, dynamic> json) =>
      _$CreateItemRequestFromJson(json);
}
  4. 返回符合技术栈的一致错误结构
  5. 若必须偏离规范，请立即停止并通知团队负责人

For Frontend Workers

前端开发人员指南

When consuming an API endpoint:
  1. Query Apidog MCP for the endpoint specification before coding
  2. Import shared types/models — never define API types locally
    • Web/TypeScript: import from 
      src/types/
    • Flutter/Dart: import from 
      lib/core/models/
  3. Handle all documented status codes appropriately for your stack:
    Web/TypeScript:
    typescript
    const response = await fetch(`/api/items/${id}`, {
  method: 'POST',
  body: JSON.stringify(data),
});

if (!response.ok) {
  // Handle each error code documented in Apidog
  const error = await response.json();
  // 400: validation error
  // 401: not authenticated
  // 404: not found
}
    Flutter/Dart:
    dart
    final response = await dio.post('/api/items/$id', data: data.toJson());
// Handle error status codes documented in Apidog
// Use either try/catch with DioException or response status checks
  4. If the API is not ready yet (backend-dev hasn't finished):
    • Use mock data that matches the Apidog spec exactly
    • Mark with a TODO comment referencing the Apidog spec endpoint ID
调用API端点时：
  1. 编码前先查询Apidog MCP获取端点规范
  2. 导入共享类型/模型——切勿在本地定义API类型
    • Web/TypeScript：从
      src/types/
      导入
    • Flutter/Dart：从
      lib/core/models/
      导入
  3. 针对技术栈妥善处理所有文档中定义的状态码：
    Web/TypeScript：
    typescript
    const response = await fetch(`/api/items/${id}`, {
  method: 'POST',
  body: JSON.stringify(data),
});

if (!response.ok) {
  // 处理Apidog文档中定义的每个错误码
  const error = await response.json();
  // 400: 验证错误
  // 401: 未认证
  // 404: 未找到
}
    Flutter/Dart：
    dart
    final response = await dio.post('/api/items/$id', data: data.toJson());
// 处理Apidog文档中定义的错误状态码
// 使用DioException的try/catch或响应状态检查
  4. 若API尚未就绪（后端开发人员未完成）：
    • 使用与Apidog规范完全匹配的模拟数据
    • 添加TODO注释并引用Apidog规范的端点ID

For Reviewer

评审人员指南

When reviewing API-related changes:
  1. Query Apidog MCP for each endpoint touched in the changeset
  2. Verify backend matches spec: request validation, response shape, error codes
  3. Verify frontend matches spec: types used, error codes handled, shapes correct
  4. Flag mismatches as Critical: any deviation from the Apidog spec must be fixed
  5. Check shared types: ensure shared types/models match the Apidog spec
评审API相关变更时：
  1. 查询Apidog MCP获取变更集中涉及的每个端点规范
  2. 验证后端是否符合规范：请求验证、响应结构、错误码
  3. 验证前端是否符合规范：使用的类型、错误码处理、结构正确性
  4. 将不匹配标记为严重问题：任何偏离Apidog规范的内容必须修复
  5. 检查共享类型：确保共享类型/模型与Apidog规范匹配

Anti-Patterns to Avoid

需要避免的反模式

  • Creating 
    contracts.md
    files manually — use Apidog MCP instead
  • Defining API types in both frontend and backend — use shared types from the central location
  • Implementing endpoints without checking Apidog first — spec drift risk
  • Using 
    any
    for API response types — defeats the purpose of contract sync
  • 手动创建
    contracts.md
    文件——改用Apidog MCP
  • 同时在前端和后端定义API类型——使用中央位置的共享类型
  • 未先检查Apidog就实现端点——存在规范漂移风险
  • 对API响应类型使用
    any
    ——违背契约同步的目的