api-contract-sync

API Contract Sync Protocol

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.

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.

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

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):

   // 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):

   // 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

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:

   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:

   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

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

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