API Design Skill

REST API design patterns. Consistent, predictable, and easy to use.

When to Activate

Activate when:

• Designing new API endpoints
• Reviewing existing API for inconsistencies
• Adding a new resource to an existing API
• Evaluating an external API design

Core Principles

• Nouns, not verbs in URLs — resources, not actions
• Consistent naming — same conventions throughout
• Standard status codes — use what HTTP intended
• No breaking changes without versioning

Resource Design

✅ Good:
GET    /api/v1/users           — list users
GET    /api/v1/users/:id       — get user by ID
POST   /api/v1/users           — create user
PUT    /api/v1/users/:id       — replace user
PATCH  /api/v1/users/:id       — update user fields
DELETE /api/v1/users/:id       — delete user

❌ Bad:
GET  /getUsers
POST /createUser
GET  /deleteUser?id=123

HTTP Methods and Status Codes

Error codes:

Error Response Format

All errors use this standard shape:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email address is invalid",
    "details": [
      { "field": "email", "message": "Must be a valid email address" }
    ]
  }
}

Pagination

Offset-based (simple, but slow on large datasets):

GET /api/v1/users?page=2&limit=20

Response:
{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 847,
    "pages": 43
  }
}

Cursor-based (efficient, consistent):

GET /api/v1/users?after=cursor_abc123&limit=20

Response:
{
  "data": [...],
  "pagination": {
    "nextCursor": "cursor_def456",
    "hasMore": true
  }
}

Filtering and Sorting

GET /api/v1/users?filter[status]=active
GET /api/v1/users?filter[role]=admin&filter[status]=active
GET /api/v1/users?sort=-createdAt          // descending
GET /api/v1/users?sort=lastName,firstName  // multiple fields

Versioning Strategy

Version in the URL path:

/api/v1/users     — current stable
/api/v2/users     — new version with breaking changes

Rules:

• Never change v1 behavior once published
• Keep v1 running for at least 12 months after v2 ships
• Document migration guide in CHANGELOG

Rate Limiting Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1609459200

Return 429 when limit exceeded with Retry-After header.

Related Skills

• backend-patterns
• postgres-patterns
• api-connector-builder