# Doncheli Api Contract

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

- **Type:** Skill
- **Install:** `agentstack add skill-doncheli-don-cheli-sdd-doncheli-api-contract`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [doncheli](https://agentstack.voostack.com/s/doncheli)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [doncheli](https://github.com/doncheli)
- **Source:** https://github.com/doncheli/don-cheli-sdd/tree/main/.opencode/skills/doncheli-api-contract
- **Website:** https://doncheli.tv

## Install

```sh
agentstack add skill-doncheli-don-cheli-sdd-doncheli-api-contract
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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: 

### 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:**
```json
{ … }
```
**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:**
```json
{ "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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-doncheli-don-cheli-sdd-doncheli-api-contract
- Seller: https://agentstack.voostack.com/s/doncheli
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.