api-design

# api-design > **Grounded corpus (Tier-1 consultation):** pagination, versioning, > error shape (RFC 9457), idempotency, async ops, rate limiting, bulk, > naming, expansion, webhooks — query `./scripts-run > <skills-root>/corpus-grounding/scripts/ground search --manifest > <skills-root>/api-design/data/manifest.json "<concern>"` and propose > the grounded pattern (+ hardening + anti-patterns + RFC link) before > designing from memory. Corpus: [`data/api-patterns.csv`](data/api-patterns.csv). ## When to use Use this skill when designing new API endpoints, restructuring existing APIs, or deciding about versioning and deprecation. Do NOT use when: - Implementing an already-designed endpoint (use `api-endpoint` skill) - Writing tests for APIs (use `api-testing` skill) ## Procedure: Design an API 1. **Gather context** — read `agents/settings/contexts/api-versioning.md`, `agents/reference/docs/api-resources.md`, `agents/reference/docs/query-filter.md`, `agents/reference/docs/controller.md`, and guideline `php/api-design.md`. 2. **Identify the resource** — determine the domain entity, its attributes, and relationships. Check existing models and resources for field naming patterns. 3. **Define endpoints** — list each endpoint with HTTP method, URL path, request body, query parameters, and response structure. Follow existing route file patterns. 4. **Decide versioning** — determine whether this extends the current version or requires a new version (see decision table below). 5....