---

name: rest-api-design description: | REST API design principles, conventions, and patterns. Use when: designing APIs, choosing status codes, error handling, caching, auth patterns. Do not use for: framework-specific implementation (use fastapi, axum skills). Workflow: This skill (design) → fastapi/axum (implementation). references:

• examples.md # Full request/response examples
• https://www.speakeasy.com/api-design/responses
• https://strapi.io/blog/rest-api-design-best-practices

---

API Design

Resource Naming

Rule: Model nouns, not verbs. HTTP methods express actions.

Copy# ❌ Verbs in URL
POST /createUser
GET /getUsers

# ✅ RESTful
POST /users
GET /users
DELETE /users/123

Rule: Plural nouns, lowercase, max 2 levels deep.

Copy# ❌ Too deep
/companies/{id}/departments/{id}/users/{id}/orders

# ✅ Flatten
/orders?userId=123

---

HTTP Methods

Rule: Idempotent = safe to retry. POST creates duplicates on retry.

---

Status Codes

Success (2xx)

Client Error (4xx)

Server Error (5xx)

Rule: 4xx = client's fault. 5xx = server's fault (retry later).

---

Response Format

Success

Copy{
  "data": { "id": 123, "name": "Ada" },
  "meta": { "requestId": "abc123" }
}

Error (RFC 9457 Problem Details)

Copy{
  "type": "https://api.example.com/errors/validation-failed",
  "title": "Validation Failed",
  "status": 422,
  "detail": "Email is required",
  "errors": [{ "field": "email", "code": "required" }]
}

Rule: Use Content-Type: application/problem+json for errors.

See examples.md for full request/response examples.

---

Request/Response Consistency

Rule: Request shape should match response shape.

Response may have read-only fields (id, createdAt), but structure must be identical. Never change field types or nesting between request/response.

---

Pagination

Rule: Prefer cursor-based. Offset has performance issues at scale.

---

Filtering & Sorting

CopyGET /users?role=admin&status=active
GET /users?sort=-createdAt
GET /users?fields=id,name,email

Rule: Filters in query string, not URL path.

---

Caching

Rule: Cache public data. private, no-store for user-specific.

---

Security

Rate limit headers:

CopyX-RateLimit-Limit: 100
X-RateLimit-Remaining: 75
Retry-After: 30

Rule: Stateless auth enables horizontal scaling. Return Retry-After with 429.

---

Versioning

Copy/v1/users
/v2/users

Rule: Version in URL. Only for breaking changes. Use Sunset header for deprecation.

---

Quick Checklist

URL Design

• Plural nouns, no verbs
• Max 2 levels nesting
• Filters in query string

HTTP

• Correct methods and status codes
• 201 + Location for create
• 204 for delete

Response

• Consistent envelope (data, meta)
• RFC 9457 for errors
• Request/response shapes match

Performance

• Pagination on collections
• Cache headers
• Field selection

Security

• HTTPS only
• Stateless auth
• Rate limiting