API Design Guide

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
  }
}

Error response:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "email",
        "code": "INVALID_FORMAT",
        "message": "Must be a valid email address"
      }
    ]
  }
}

---

Pagination

Offset-based (simple, but slow on large datasets):

GET /​users?page=2&perPage=20
GET /​users?offset=40&limit=20

Cursor-based (efficient, recommended):

GET /​users?cursor=eyJpZCI6MTIzfQ&limit=20

Response includes next cursor:

{
  "data": [...],
  "meta": {
    "nextCursor": "eyJpZCI6MTQzfQ",
    "hasMore": true
  }
}

---

Filtering, Sorting, Fields

Filtering:

GET /​users?status=active
GET /​users?created_after=2024-01-01
GET /​users?role=admin,moderator

Sorting:

GET /​users?sort=name
GET /​users?sort=-created_at         # Descending
GET /​users?sort=status,-created_at  # Multiple fields

Field selection:

GET /​users?fields=id,name,email
GET /​users?include=orders,profile

---

Versioning

URL path (recommended):

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

Header:

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

---

OpenAPI Specification

openapi: 3.0.3
info:
  title: My API
  version: 1.0.0
  description: API for managing users

servers:
  - url: https://api.example.com/v1

paths:
  /​users:
    get:
      summary: List users
      tags: [Users]
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        "200":
          description: List of users
          content:
            application/​json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/​components/​schemas/​User"

components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id:
          type: string
        email:
          type: string
          format: email
        name:
          type: string

---

Authentication

API Keys (simple, for server-to-server):

Authorization: Api-Key YOUR_API_KEY

Bearer Tokens (JWT, OAuth):

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Include in OpenAPI:

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []

---

Rate Limiting

Include headers in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Return 429 Too Many Requests when exceeded.

---

Security Checklist

• HTTPS only
• Authentication on protected routes
• Input validation
• Output encoding
• Rate limiting
• CORS configuration
• No sensitive data in URLs
• Audit logging