API Contracts

The OpenAPI file is the API source of truth.

Target Files

packages/contracts/
├── openapi.yaml
├── generated-typescript/
└── generated-dart/

Contract Rules

• Use /api/v1 for versioned endpoints.
• Include request and response schemas for every operation.
• Include validation constraints, examples, and error responses.
• Define standard schemas for IDs, timestamps, pagination, money, and errors.
• Mark required and nullable fields explicitly.
• Do not expose persistence entities.
• Do not manually edit generated clients.

Standard Error Shape

{
  "type": "VALIDATION_ERROR",
  "title": "Request validation failed",
  "status": 400,
  "traceId": "abc-123",
  "fieldErrors": {
    "email": "Invalid email address"
  }
}

Generation Flow

flowchart LR
    A["Edit openapi.yaml"] --> B["Lint contract"]
    B --> C["Check for breaking changes"]
    C --> D["Generate backend interfaces"]
    C --> E["Generate TypeScript client"]
    C --> F["Generate Dart client"]
    D --> G["Implement backend"]
    E --> H["Implement web"]
    F --> I["Implement mobile"]

CI Requirements

• Lint OpenAPI.
• Run breaking-change detection against the base branch.
• Regenerate clients.
• Fail if generated output is stale.
• Run backend contract tests.