api-design

API Design Guide

Best practices for designing developer-friendly, maintainable APIs.

REST API Principles

Resource Naming

Use nouns, not verbs:

✓ GET /users
✓ GET /users/123
✓ GET /users/123/orders

✗ GET /getUsers
✗ GET /fetchUserById
✗ POST /createNewOrder

Use plural nouns:

✓ /users
✓ /orders
✓ /products

✗ /user
✗ /order

Hierarchical relationships:

/users/{userId}/orders           # User's orders
/users/{userId}/orders/{orderId} # Specific order

HTTP Methods

Status Codes

Success (2xx):

• 200 OK - Request succeeded
• 201 Created - Resource created (return Location header)
• 204 No Content - Success with no response body

Client Error (4xx):

• 400 Bad Request - Malformed request
• 401 Unauthorized - Authentication required
• 403 Forbidden - No permission
• 404 Not Found - Resource doesn't exist
• 409 Conflict - State conflict
• 422 Unprocessable Entity - Validation failed
• 429 Too Many Requests - Rate limited

Server Error (5xx):

• 500 Internal Server Error - Unexpected error
• 503 Service Unavailable - Temporary outage

Response Format

Successful response:

{
  "data": {
    "id": "123",
    "name": "John Doe",
    "email": "[email protected]"
  }
}

Collection response:

{
  "data": [
    { "id": "1", "name": "Item 1" },
    { "id": "2", "name": "Item 2" }
  ],
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 100,
    "totalPages": 5
  },
  "links": {
    "self": "/items?page=1",
    "next": "/items?page=2",
    "prev": null
  }
}