Agent skill · software engineering · aiskillstore
api-design
REST API design best practices for consistent, intuitive APIs
Why this skill is useful
Codifies REST API design principles that the AI could infer but now doesn't have to guess.
What it needs
About 3k tokens when loaded. Last updated 2026-08-07. 405 stars on the source repository.
What this skill does
API Design Principles Design APIs that are intuitive, consistent, and a joy to use. URL Structure Resources as Nouns Plural Resource Names Hierarchical Relationships HTTP Methods Method Usage Idempotent Safe -------- ------- ------------ ------ GET Read resource Yes Yes POST Create resource No No PUT Replace resource Yes No PATCH Partial update Yes No DELETE Remove resource Yes No Request/Response Format Consistent JSON Structure Use camelCase Status Codes Success (2xx) Client Errors (4xx) Server Errors (5xx) Pagination Offset-based (simple) Cursor-based (scalable) Filtering & Sorting Filtering Sorting Field Selection Versioning URL Path (recommended) Header Authentication Bearer Token API Key Rate Limiting Include headers: Documentation Every endpoint needs: Description of what it does Request parameters with types Request body schema Response schema for each status code Example request/response Error cases Common Mistakes Mistake Problem Fix --------- --------- ----- Verbs in URLs /getUser Use /users/:id Inconsistent naming Mix of cases Pick one (camelCase) Wrong status codes 200 for errors Use 4xx/5xx appropriately No pagination Memory issues Always paginate collections Breaking changes Clients break Version your API No rate limiting Abuse Implement limits Exposing internals Security risk Transform responses Checklist [ ] URLs use nouns, not verbs [ ] HTTP methods used correctly [ ] Consistent response format [ ] Appropriate status codes [ ] Pagination for collections [ ] Filtering and sorting support [ ] Rate limiting implemented [ ] Authentication documented [ ] Errors are descriptive [ ] API is versioned
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills aiskillstore/api-design