api-design

Files (1)

• SKILL.md

SKILL.md (first lines)

# api-design

Design the API contract. No code edits, no implementation — wait for confirmation before coding.

1. Read 1-2 existing endpoints. Extract URL pattern, response envelope, error shape, auth mechanism, status codes — match ALL in the new design.
2. Changing an EXISTING endpoint → grep for callers first. Non-breaking → propose a backwards-compatible alternative. Breaking → version transition below.

## Version transitions (breaking changes only)

Breaking = removed/renamed field, required field added, type/status-code/error-format/auth changed, endpoint removed. Non-breaking (no versioning): new optional field/param, new endpoint.
Plan: current `/api/v[N]` → new `/api/v[N+1]`, both live in parallel — never remove old behavior on deploy. Old version gets `Deprecation` + `Sunset` + `Link` headers; sunset ≥6 months after v[N+1] ships. Write `docs/api-migration-vN-to-vN+1.md`, update OpenAPI spec, regenerate types.
Deep reference: `${CLAUDE_PLUGIN_ROOT}/agent_docs/api-versioning-guide.md` — parallel routing code, deprecation headers, migration guide template, OpenAPI dual-version strategy.

## Output

```text
ENDPOINT: [METHOD] [/path/:param] | AUTH: [guard name | none | role:admin]
REQUEST: headers / params / body (with types) | RESPONSE 200/201: { field: type } ← match existing envelope
ERRORS: 400/401/403/404 — when each applies | IDEMPOTENCY: [required|not] | RATE LIMIT: [required|not]
BREAKING CHANGE RISK: [none|low|HIGH→mitigation] | OPEN QUESTIONS: [none|must-answer]
```

Every mutating endpoint needs auth. Sensitive endpoints must be rate-limited. Never implement — wait for "go".

From mtvrkan/senior-dev-kit, MIT.

More from mtvrkan/senior-dev-kit