API Design Patterns

Designing Great APIs

Well-designed APIs are intuitive, consistent, and developer-friendly.

Versioning Strategies

• URL Path: /api/v1/users (most common)
• Query Param: /api/users?version=1
• Header: Accept: application/vnd.api+json;version=1

Pagination

// Cursor-based (recommended)
{
  "data": [...],
  "nextCursor": "abc123",
  "hasMore": true
}

// Offset-based
{
  "data": [...],
  "page": 1,
  "totalPages": 10
}

Error Responses

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "details": [
      { "field": "email", "message": "Invalid format" }
    ]
  }
}

Documentation

• OpenAPI/Swagger: API specification standard
• Postman: API documentation and testing
• Readme.com: Developer documentation platform