api-designlisted

# api-design ## 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. **Design error responses** — define 4xx/5xx responses matching the project's existing error format. 6. **Validate against existing patterns** — compare your design with 2-3 similar existing endpoints. Flag any inconsistencies. 7. **Run adversarial review** — use `adversarial-review` skill to check for breaking changes, consistency issues, and missing error cases. ## Versioning decisions ### URL-based versioning Routes versioned via URL prefix: `/api/v1/...`, `/api/v2/...` ```