The API Design Principles That Prevent Support Tickets

Good API design eliminates confusion. Here's how. 🔌

1. Be Predictable ✅ GET /users/{id} (gets one user) ✅ GET /users (gets all users) ❌ GET /user/{id} vs GET /users (inconsistent)

2. Use HTTP Status Codes Correctly • 200: Success with data • 201: Created successfully • 400: Client error (bad request) • 401: Unauthorized • 404: Not found • 500: Server error

❌ Returning 200 with error in body ✅ Return appropriate status + error details

3. Consistent Response Format

{
  "data": {...},
  "message": "Success",
  "timestamp": "2025-09-15T10:00:00Z",
  "requestId": "abc-123"
}

4. Include Pagination Meta

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

5. Validate Input Properly

{
  "error": "Validation failed",
  "details": [
    {
      "field": "email",
      "message": "Invalid email format",
      "code": "INVALID_EMAIL"
    }
  ]
}

6. Version Your APIs • URL: /api/v1/users • Header: Accept: application/vnd.api+json;version=1 • Never break existing versions

7. Use Clear Naming ✅ /orders/{orderId}/items ❌ /getOrderItemsByOrderId

8. Support Filtering & Sorting GET /users?status=active&sort=createdAt&order=desc

The Golden Rule: Your API should be so intuitive that documentation is optional, not mandatory.

Developers should be able to guess the endpoint structure and it should just work.

What's your biggest API design pet peeve? 🤷‍♂️