Core Principles of API Design

APIs are the contracts between systems. A well-designed API is not only functional but also predictable, consistent, and future-proof. Poor design leads to confusion, misuse, and costly rewrites. This chapter explores the core principles that guide scalable and developer-friendly API design.

1️⃣ Consistency in Resource Naming and Structure

Consistency is key to usability. Clients should be able to guess an endpoint or understand a response without always checking documentation.

• Resource-oriented naming (use nouns, not verbs):

  /users/123/orders // clear, resource-based
  /getUserOrders?id=123 // action-based, inconsistent)

• Plural nouns for collections:

  /users
  /users/{id}
  /users/{id}/posts

• Standard HTTP methods:
  • GET /users: Retrieve users
  • POST /users: Create user
  • PUT /users/{id}: Update user
  • DELETE /users/{id}: Delete user

2️⃣ Statelessness and Scalability

APIs should be stateless: each request must contain all necessary information for the server to process it:

• Don't rely on server-side sessions.
• Use tokens (JWT, OAuth2) for authentication.
• Benefits: scalability, fault tolerance, easier load balancing.

Example:

GET /orders/123
Authorization: Bearer <token>

The server can validate the request without remembering prior interactions.

3️⃣ Idempotency

Idempotency means that repeating the same request produces the same result.

• GET is naturally idempotent (multiple GETs = no side effects).
• PUT should overwrite an entity without duplicating.
• DELETE should succeed even if the resource no longer exists.

Why it matters:

• Prevents duplicate charges/orders in case of retries.
• Ensures APIs are safe under network failures.

Example:

PUT /orders/123
{
  "status": "cancelled"
}

No matter how many times it's called, the order stays cancelled.

4️⃣ Versioning Strategies

APIs evolve over time. A breaking change should never silently disrupt clients.

• URI-based versioning:

  /api/v1/users
  /api/v2/users
  

• Header-based versioning:

  Accept: application/vnd.api+json; version=2
  

• Best practice: Plan for backward compatibility, and always provide a deprecation path.

5️⃣ Pagination, Filtering, and Sorting

Large datasets should never be returned in a single response.

• Pagination:

  GET /users?page=2&limit=50
  

• Filtering:

  GET /users?role=admin&status=active
  

• Sorting:

  GET /users?sort=created_at&order=desc
  

• Response example:

  {
    "data": [...],
    "pagination": {
      "page": 2,
      "limit": 50,
      "total": 1000
    }
  }
  

6️⃣ Structured Error Handling

Errors should be predictable and structured so that clients can handle them programmatically.

• Use standard HTTP status codes:
  • 200 OK: Success
  • 400 Bad Request: Client error
  • 401 Unauthorized: Invalid credentials
  • 404 Not Found: Resource missing
  • 500 Internal Server Error: Unexpected server error

• Error response format:

  {
    "error": {
      "code": "USER_NOT_FOUND",
      "message": "User with ID 123 does not exist",
      "details": {
        "id": 123
      }
    }
  }
  

7️⃣ Example: A Well-Designed Endpoint

GET /api/v1/users/123/orders?status=active&limit=10

Response:

{
  "data": [
    { "id": 1, "item": "Laptop", "status": "active" },
    { "id": 2, "item": "Headphones", "status": "active" }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 25
  },
  "meta": {
    "request_id": "abc-xyz-123",
    "timestamp": "2025-08-27T09:00:00Z"
  }
}

• Consistent resoruce naming (/users/123/orders).
• Stateless (auth token required per request).
• Idempotent if repeated.
• Versioned (/v1).
• Paginated results.
• Structured errors & metadata included.