# API Design Review Skill

## Purpose
Review REST API designs for consistency, best practices, and developer experience.

## Naming Conventions
- Use plural nouns for resources: /users, /products, /orders
- Avoid verbs in URLs: GET /users (not GET /getUsers)
- Use kebab-case for multi-word: /order-items (not /orderItems)
- Keep URLs flat: /users/:id/orders (not /users/:id/orders/:orderId/items/:itemId)

## HTTP Methods
- GET: read (200 OK)
- POST: create (201 Created with Location header)
- PUT: full update (200 OK)
- PATCH: partial update (200 OK)
- DELETE: remove (204 No Content)

## Error Handling
Use consistent error response format:
```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "details": [{ "field": "email", "message": "must not be empty" }]
  }
}
```

## Pagination
Always paginate list endpoints:
```
GET /users?page=2&limit=20
Response: { data: [...], meta: { page: 2, limit: 20, total: 150 } }
```

## Filtering and Sorting
- Filter: GET /users?role=admin&status=active
- Sort: GET /users?sort=-createdAt,name
- Fields: GET /users?fields=id,name,email