# API Design

> Design or review stable APIs with explicit contracts, errors, authorization, idempotency, pagination, compatibility, and evolution.

- Skill: `egeetas/api-design` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add egeetas/api-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/egeetas/api-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: egeetas (https://skillmd.com/u/egeetas)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/egeetas/api-design

---


# API Design

Start from consumer tasks and domain semantics rather than transport mechanics.

## Contract

- Define resources/actions, inputs, outputs, invariants, ownership, authorization, and side effects.
- Specify validation, error categories, retryability, timeouts, cancellation, and partial failure.
- Use idempotency for retryable mutations and define concurrency/conflict semantics.
- Design pagination, filtering, ordering, field selection, limits, and consistency explicitly.
- Bound payloads and document rate limits, quotas, and abuse controls.
- Use stable names and additive evolution; document deprecation, versioning, and migration for breaking changes.

Provide representative success and failure examples plus contract tests. For event APIs, also define delivery guarantees, ordering, duplication, schema evolution, replay, and dead-letter handling.