doncheli-api-contract

# Don Cheli: API Contract Designer ## Instructions 1. Identify the API style: REST, GraphQL, gRPC, Webhook, or mixed 2. For each resource/operation, define: - Method + path (REST) or operation name (GraphQL/gRPC) - Request schema: headers, path params, query params, body - Response schemas: success + all error cases 3. Design cross-cutting concerns: - **Auth**: mechanism (JWT, OAuth2, API Key, mTLS), scopes, token lifetime - **Rate limiting**: strategy (token bucket / leaky bucket), limits per tier, headers exposed - **Error handling**: standard error envelope, HTTP status mapping, error codes catalog - **Retries**: which operations are safe to retry, backoff strategy, max attempts - **Circuit breaker**: thresholds, half-open probe, fallback behavior - **Idempotency**: which operations require idempotency keys, TTL, conflict semantics 4. Define versioning strategy (URL path, header, or content negotiation) 5. Flag breaking vs. non-breaking changes policy ## Output Format ``` ## API Contract: <service/feature name> ### Style & Version - Protocol: REST / GraphQL / gRPC / Webhook - Base URL: … - Version: v1 (strategy: <path/header/content-negotiation>) ### Endpoints / Operations #### <METHOD> <path> **Purpose:** … **Auth required:** yes/no — scope: … **Request:** ```json { "field": "type — description" } ``` **Response 200:** ```json { … } ``` **Error responses:** | Status | Code | Meaning | |--------|---------------|----...