api-design
Installation
SKILL.md
API Design
Apply these conventions when designing, reviewing, or implementing RESTful APIs. Consistency matters more than cleverness — follow the patterns below.
URL Structure
Use nouns for resources, not verbs. Resources are things, not actions.
| Rule | Correct | Incorrect |
|---|---|---|
| Plural nouns | /users, /orders |
/user, /getOrders |
| Nouns, not verbs | POST /users |
POST /createUser |
| Kebab-case for multi-word | /line-items |
/lineItems, /line_items |
| Nest for relationships (max 2 levels) | /users/:id/orders |
/users/:id/orders/:orderId/items/:itemId |
| Flat when parent is obvious | /orders/:orderId/items |
/users/:userId/orders/:orderId/items |
Query Parameters
Use query parameters for filtering, sorting, searching, and pagination. Never encode these in the URL path.