API Contract Sync Protocol

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

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

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

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

For Frontend Workers

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

For Reviewer

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