Api Design
Apply REST conventions—resources, status codes, pagination, errors, versioning, and rate limits—when designing or reviewing APIs with your coding agent.
Overview
API Design is an agent skill most often used in Build (also Ship review, Validate scope) that teaches REST resource naming, status codes, pagination, errors, versioning, and rate limiting for production APIs.
Install
npx skills add https://github.com/affaan-m/everything-claude-code --skill api-designWhat is this skill?
- Resource URL rules: plural nouns, kebab-case, nested ownership, no verbs in paths
- CRUD mapping with PATCH/PUT guidance and sparse action verbs for cancel/login/refresh
- Pagination, filtering, sorting, and query-param conventions for list endpoints
- Consistent error response shapes, HTTP status code usage, and versioning strategy
- Rate limiting patterns for public and partner-facing APIs
Adoption & trust: 6.2k installs on skills.sh; 210k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are adding REST endpoints but lack a shared contract for URLs, errors, pagination, and versioning across your solo project.
Who is it for?
Indie SaaS and API builders using Claude Code who want opinionated REST checklists before coding handlers or publishing OpenAPI.
Skip if: GraphQL-only or gRPC-first services where REST path conventions are irrelevant—use a transport-specific skill instead.
When should I use this skill?
Designing new API endpoints, reviewing existing API contracts, adding pagination/filtering/sorting, implementing API error handling, planning versioning, or building public or partner-facing APIs.
What do I get? / Deliverables
After the skill runs, you have aligned endpoint sketches and review notes that follow consistent REST patterns ready to implement or merge.
- Endpoint map with methods and URL patterns
- Error and pagination conventions documented for implementation
- Review notes on naming and status-code anti-patterns
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
New endpoints and contracts are authored during Build; this skill’s canonical shelf is backend API design even though the same rules apply at Ship review. Backend subphase is where resource URLs, HTTP verbs, and error envelopes are decided before frontend wiring.
Where it fits
Draft users and orders routes with plural kebab-case paths and nested POST /users/:id/orders.
Define the smallest v1 surface and auth login/refresh verb endpoints before building the full backend.
Check list endpoints for pagination query params and consistent 4xx/5xx error bodies before partner docs go live.
How it compares
Use as a design-and-review playbook instead of one-off chat suggestions that mix verbs in URLs and ambiguous status codes.
Common Questions / FAQ
Who is api-design for?
Solo developers and small teams building REST backends with Claude Code, Cursor, or Codex who need repeatable API contract rules.
When should I use api-design?
Use it in Build/backend when designing endpoints; in Validate/scope when locking a minimal public API for an MVP; and in Ship/review when auditing pagination, errors, and versioning before release.
Is api-design safe to install?
See the Security Audits panel on this Prism page; the skill is documentation-only pattern guidance with no required shell or secret access.
SKILL.md
READMESKILL.md - Api Design
# API Design Patterns Conventions and best practices for designing consistent, developer-friendly REST APIs. ## When to Activate - Designing new API endpoints - Reviewing existing API contracts - Adding pagination, filtering, or sorting - Implementing error handling for APIs - Planning API versioning strategy - Building public or partner-facing APIs ## Resource Design ### URL Structure ``` # Resources are nouns, plural, lowercase, kebab-case GET /api/v1/users GET /api/v1/users/:id POST /api/v1/users PUT /api/v1/users/:id PATCH /api/v1/users/:id DELETE /api/v1/users/:id # Sub-resources for relationships GET /api/v1/users/:id/orders POST /api/v1/users/:id/orders # Actions that don't map to CRUD (use verbs sparingly) POST /api/v1/orders/:id/cancel POST /api/v1/auth/login POST /api/v1/auth/refresh ``` ### Naming Rules ``` # GOOD /api/v1/team-members # kebab-case for multi-word resources /api/v1/orders?status=active # query params for filtering /api/v1/users/123/orders # nested resources for ownership # BAD /api/v1/getUsers # verb in URL /api/v1/user # singular (use plural) /api/v1/team_members # snake_case in URLs /api/v1/users/123/getOrders # verb in nested resource ``` ## HTTP Methods and Status Codes ### Method Semantics | Method | Idempotent | Safe | Use For | |--------|-----------|------|---------| | GET | Yes | Yes | Retrieve resources | | POST | No | No | Create resources, trigger actions | | PUT | Yes | No | Full replacement of a resource | | PATCH | No* | No | Partial update of a resource | | DELETE | Yes | No | Remove a resource | *PATCH can be made idempotent with proper implementation ### Status Code Reference ``` # Success 200 OK — GET, PUT, PATCH (with response body) 201 Created — POST (include Location header) 204 No Content — DELETE, PUT (no response body) # Client Errors 400 Bad Request — Validation failure, malformed JSON 401 Unauthorized — Missing or invalid authentication 403 Forbidden — Authenticated but not authorized 404 Not Found — Resource doesn't exist 409 Conflict — Duplicate entry, state conflict 422 Unprocessable Entity — Semantically invalid (valid JSON, bad data) 429 Too Many Requests — Rate limit exceeded # Server Errors 500 Internal Server Error — Unexpected failure (never expose details) 502 Bad Gateway — Upstream service failed 503 Service Unavailable — Temporary overload, include Retry-After ``` ### Common Mistakes ``` # BAD: 200 for everything { "status": 200, "success": false, "error": "Not found" } # GOOD: Use HTTP status codes semantically HTTP/1.1 404 Not Found { "error": { "code": "not_found", "message": "User not found" } } # BAD: 500 for validation errors # GOOD: 400 or 422 with field-level details # BAD: 200 for created resources # GOOD: 201 with Location header HTTP/1.1 201 Created Location: /api/v1/users/abc-123 ``` ## Response Format ### Success Response ```json { "data": { "id": "abc-123", "email": "alice@example.com", "name": "Alice", "created_at": "2025-01-15T10:30:00Z" } } ``` ### Collection Response (with Pagination) ```json { "data": [ { "id": "abc-123", "name": "Alice" }, { "id": "def-456", "name": "Bob" } ], "meta": { "total": 142, "page": 1, "per_page": 20, "total_pages": 8 }, "links": { "self": "/api/v1/users?page=1&per_page=20", "next": "/api/v1/users?page=2&per_page=20", "last": "/api/v1/users?page=8&per_page=20" } } ``` ### Error Response ```json { "error": { "code": "validation_error", "message": "Request validation failed", "details": [ { "field":