Api Design

Overview

API design encompasses the principles, patterns, and practices for creating effective, maintainable, and scalable APIs.

Design Principles

API-First Development

• Design APIs before implementation
• Contract-driven development
• Consumer-centric approach

Consistency

• Uniform naming conventions
• Consistent error handling
• Standard HTTP status codes

Simplicity

• Keep interfaces simple and intuitive
• Avoid over-engineering
• Progressive disclosure of complexity

Extensibility

• Design for future changes
• Versioning strategies
• Backward compatibility

Resource Modeling

Identify Resources

• Nouns representing domain entities
• Hierarchical relationships
• Resource lifecycle

Resource Representations

• JSON as primary format
• Consistent field naming (camelCase vs snake_case)
• Include metadata (timestamps, links)

Hypermedia

• HATEOAS principles
• Self-describing APIs
• Navigation links in responses

URL Design

RESTful URL Patterns

/api/v1/users              # Collection
/api/v1/users/{id}         # Individual resource
/api/v1/users/{id}/posts   # Sub-resources
/api/v1/posts?user=123     # Filtering
/api/v1/posts?page=2       # Pagination

URL Best Practices

• Use lowercase letters
• Use hyphens for multi-word resources
• Avoid query parameters for resource identification
• Keep URLs readable and predictable

HTTP Methods & Status Codes

Method Selection

• GET for safe read operations
• POST for creating resources
• PUT for full resource updates
• PATCH for partial updates
• DELETE for resource removal

Status Code Guidelines

• 200 for successful GET/PUT/PATCH
• 201 for successful POST (resource created)
• 204 for successful DELETE (no content)
• 400 for client errors (bad request)
• 401 for authentication required
• 403 for authorization failed
• 404 for resource not found
• 422 for validation errors
• 500 for server errors

OpenAPI Specification

API Documentation

openapi: 3.0.3
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: Successful response

Benefits

• Machine-readable API documentation
• Code generation capabilities
• Automated testing
• Client SDK generation

Versioning Strategies

URL Versioning

/v1/users
/v2/users

Header Versioning

Accept: application/vnd.api.v1+json

Query Parameter Versioning

/users?version=1

Media Type Versioning

Content-Type: application/vnd.company.user.v2+json

Error Handling

Error Response Format

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

Error Code Standards

• Use consistent error codes
• Include helpful error messages
• Provide debugging information
• Avoid exposing internal details

Pagination

Offset-Based Pagination

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "totalPages": 10
  }
}

Cursor-Based Pagination

{
  "data": [...],
  "pagination": {
    "nextCursor": "abc123",
    "hasNextPage": true
  }
}

Filtering & Sorting

Query Parameters

/users?status=active&sort=name&order=asc

Filter Operators

• eq (equals)
• ne (not equals)
• gt (greater than)
• lt (less than)
• in (in array)

Rate Limiting

Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Strategies

• Fixed window
• Sliding window
• Token bucket
• Leaky bucket

Detailed Topics

Resource Modeling

• Resource Modeling - Designing effective API resources with entities, relationships, and representations

URL Design Patterns

• Url Design Patterns - Creating intuitive, consistent, and maintainable API URLs

Related

• Rest Apis
• Graphql
• Api Documentation
• Api Security