API Design

Overview

API design defines how services expose capabilities to clients. Good API design improves reliability, discoverability, and long-term compatibility.

Design Principles

• Resource-oriented endpoints
• Consistent naming and status codes
• Backward-compatible versioning
• Explicit error models

sequenceDiagram
    participant Client
    participant API
    participant Service
    Client->>API: GET /v1/orders/1452
    API->>Service: Fetch order
    Service-->>API: Order data
    API-->>Client: 200 OK + JSON

Practical Example

GET /v1/orders/1452
Accept: application/json

{
  "orderId": "1452",
  "status": "SHIPPED",
  "total": 149.90,
  "currency": "USD"
}

Error responses should stay consistent:

{
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "Order 1452 was not found",
    "traceId": "a18d9f"
  }
}

Common Pitfalls

• Breaking response schema without versioning
• Overloading endpoints with mixed responsibilities
• Returning ambiguous errors without machine-readable codes

Key Takeaways

• Consistency and compatibility are foundational API qualities.
• Versioning and error standards reduce integration failures.
• Clear contracts speed up client development.