---
name: ecc-api-design
description: REST API design patterns including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting for production APIs.
---

# 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

## 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

# Actions that don't map to CRUD (use verbs sparingly)
POST   /api/v1/orders/:id/cancel
```

### Naming Rules
```
# GOOD
/api/v1/team-members           # kebab-case for multi-word resources
/api/v1/orders?status=active   # query params for filtering

# BAD
/api/v1/getUsers               # verb in URL
/api/v1/user                   # singular (use plural)
```

## HTTP Methods and Status Codes

| Method | Idempotent | Safe | Use For |
|--------|-----------|------|---------|
| GET | Yes | Yes | Retrieve resources |
| POST | No | No | Create resources, trigger actions |
| PUT | Yes | No | Full replacement |
| PATCH | No* | No | Partial update |
| DELETE | Yes | No | Remove a resource |

### Status Code Reference
- **200** OK — GET, PUT, PATCH
- **201** Created — POST (include Location header)
- **204** No Content — DELETE, PUT
- **400** Bad Request — Validation failure
- **401** Unauthorized — Missing/invalid auth
- **403** Forbidden — Authenticated but not authorized
- **404** Not Found — Resource doesn't exist
- **409** Conflict — Duplicate entry, state conflict
- **422** Unprocessable Entity — Valid JSON, bad data
- **429** Too Many Requests — Rate limit exceeded
- **500** Internal Server Error — Never expose details

## Pagination

### Offset-Based (Simple)
```
GET /api/v1/users?page=2&per_page=20
```
**Pros:** Easy, supports "jump to page N"
**Cons:** Slow on large offsets

### Cursor-Based (Scalable)
```
GET /api/v1/users?cursor=***&limit=20
```
**Pros:** Consistent performance, stable with concurrent inserts
**Cons:** Cannot jump to arbitrary page

## Response Format

### Success
```json
{
  "data": { "id": "abc-123", "email": "alice@example.com", "name": "Alice" },
  "meta": { "total": 142, "page": 1, "per_page": 20 },
  "links": { "self": "/api/v1/users?page=1", "next": "/api/v1/users?page=2" }
}
```

### Error
```json
{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "details": [{"field": "email", "message": "Must be valid email"}]
  }
}
```

## Rate Limiting Headers
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000
```
When exceeded: `HTTP 429` with `Retry-After: 60`

## Versioning
- Start with `/api/v1/`
- Maintain at most 2 active versions
- Non-breaking changes don't need a new version
- Add `Sunset` header for deprecated endpoints
