Don Cheli: API Contract Designer
Instructions
- Identify the API style: REST, GraphQL, gRPC, Webhook, or mixed
- 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
- 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
- Define versioning strategy (URL path, header, or content negotiation)
- 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:
{ … }
Error responses:
| Status |
Code |
Meaning |
| 400 |
INVALID_INPUT |
… |
| 409 |
CONFLICT |
… |
Idempotency: required / not required — key:
Cross-Cutting Concerns
Auth: …
Rate Limiting: X req/min per API key; headers: X-RateLimit-Remaining, X-RateLimit-Reset
Retry Policy: safe methods (GET, PUT, DELETE) — exponential backoff, max 3 attempts
Circuit Breaker: open at 50% error rate over 10s window; half-open probe after 30s
Error Envelope:
{ "error": { "code": "…", "message": "…", "trace_id": "…" } }
Breaking Change Policy
- Breaking: removing fields, changing types, removing endpoints → requires major version bump
- Non-breaking: adding optional fields, new endpoints → compatible within same version
## Quality Gate
- Every endpoint must have at least one documented error response
- Idempotency policy must be explicit (required or not required) for every mutating operation
- Auth scopes must be listed for every endpoint that requires authentication
- Rate limit headers must be named consistently across all endpoints
## Do not use this skill when
- The API already exists and the user wants to review it (use doncheli-review instead)
- The user only wants implementation, not contract design (use doncheli-implement instead)
1---2name: doncheli-api-contract3description: Design complete API contracts covering endpoints, auth, rate limiting, error handling, retries, circuit breaker and idempotency. Activate when user mentions "api contract", "api design", "endpoint", "webhook", "REST", "GraphQL", "OpenAPI", "design the API".4---5
6# Don Cheli: API Contract Designer
7
8## Instructions
9
101. Identify the API style: REST, GraphQL, gRPC, Webhook, or mixed
112. For each resource/operation, define:
12 - Method + path (REST) or operation name (GraphQL/gRPC)
13 - Request schema: headers, path params, query params, body
14 - Response schemas: success + all error cases
153. Design cross-cutting concerns:
16 - **Auth**: mechanism (JWT, OAuth2, API Key, mTLS), scopes, token lifetime
17 - **Rate limiting**: strategy (token bucket / leaky bucket), limits per tier, headers exposed
18 - **Error handling**: standard error envelope, HTTP status mapping, error codes catalog
19 - **Retries**: which operations are safe to retry, backoff strategy, max attempts
20 - **Circuit breaker**: thresholds, half-open probe, fallback behavior
21 - **Idempotency**: which operations require idempotency keys, TTL, conflict semantics
224. Define versioning strategy (URL path, header, or content negotiation)
235. Flag breaking vs. non-breaking changes policy
24
25## Output Format
26
27```
28## API Contract: <service/feature name>
29
30### Style & Version
31- Protocol: REST / GraphQL / gRPC / Webhook
32- Base URL: …
33- Version: v1 (strategy: <path/header/content-negotiation>)
34
35### Endpoints / Operations
36
37#### <METHOD> <path>
38**Purpose:** …
39**Auth required:** yes/no — scope: …
40**Request:**
41```json
42{
43 "field": "type — description"
44}
45```
46**Response 200:**
47```json
48{ … }
49```
50**Error responses:**
51| Status | Code | Meaning |
52|--------|---------------|----------------------|
53| 400 | INVALID_INPUT | … |
54| 409 | CONFLICT | … |
55
56**Idempotency:** required / not required — key: <header name>
57
58---
59
60### Cross-Cutting Concerns
61
62**Auth:** …
63**Rate Limiting:** X req/min per API key; headers: X-RateLimit-Remaining, X-RateLimit-Reset
64**Retry Policy:** safe methods (GET, PUT, DELETE) — exponential backoff, max 3 attempts
65**Circuit Breaker:** open at 50% error rate over 10s window; half-open probe after 30s
66**Error Envelope:**
67```json
68{ "error": { "code": "…", "message": "…", "trace_id": "…" } }
69```
70
71### Breaking Change Policy
72- Breaking: removing fields, changing types, removing endpoints → requires major version bump
73- Non-breaking: adding optional fields, new endpoints → compatible within same version
74```
75
76## Quality Gate
77
78- Every endpoint must have at least one documented error response
79- Idempotency policy must be explicit (required or not required) for every mutating operation
80- Auth scopes must be listed for every endpoint that requires authentication
81- Rate limit headers must be named consistently across all endpoints
82
83## Do not use this skill when
84
85- The API already exists and the user wants to review it (use doncheli-review instead)
86- The user only wants implementation, not contract design (use doncheli-implement instead)
aibot88