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

1. 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

1. Define versioning strategy (URL path, header, or content negotiation)
2. Flag breaking vs. non-breaking changes policy

Output Format

## API Contract: 

### Style & Version
- Protocol: REST / GraphQL / gRPC / Webhook
- Base URL: …
- Version: v1 (strategy: )

### Endpoints / Operations

####  
**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)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [doncheli](https://github.com/doncheli)
- **Source:** [doncheli/don-cheli-sdd](https://github.com/doncheli/don-cheli-sdd)
- **License:** Apache-2.0
- **Homepage:** https://doncheli.tv

Install and usage instructions live in the source repository linked above.