Best Practices

v1 (current — used by 500K mobile users):
  GET /api/v1/users/42
  Response: { "id": 42, "name": "Alice", "email": "alice@example.com" }

v2 (new — splits name into first/last):
  GET /api/v2/users/42
  Response: { "id": 42, "firstName": "Alice", "lastName": "Smith", "email": "alice@example.com" }

Both versions run simultaneously.
v1 clients keep working. New clients use v2.
After 6 months, deprecate v1 with a sunset header.

First request:
  POST /api/payments
  Idempotency-Key: pay_abc123xyz
  Body: { "amount": 200, "currency": "USD", "to": "merchant_42" }

  Server:
    1. Check: has "pay_abc123xyz" been processed? → No
    2. Process payment → success
    3. Store: { key: "pay_abc123xyz", result: { id: "txn_789", status: "success" } }
    4. Return: 201 Created { "id": "txn_789", "status": "success" }

Retry (same key):
  POST /api/payments
  Idempotency-Key: pay_abc123xyz
  Body: { "amount": 200, "currency": "USD", "to": "merchant_42" }

  Server:
    1. Check: has "pay_abc123xyz" been processed? → Yes
    2. Return stored result: 200 OK { "id": "txn_789", "status": "success" }
    3. Payment NOT processed again

Page 1: GET /api/products?limit=20&offset=0
Page 2: GET /api/products?limit=20&offset=20
Page 3: GET /api/products?limit=20&offset=40

SQL: SELECT * FROM products ORDER BY id LIMIT 20 OFFSET 40

Problem at scale:
  OFFSET 1000000 → database scans and skips 1M rows before returning 20
  This gets slower and slower as offset increases

Problem with mutations:
  User is on page 2 (offset=20). A new product is inserted at position 5.
  Page 3 (offset=40) now includes a product that was already on page 2.
  → Duplicate items in the feed

Page 1: GET /api/products?limit=20
Response: {
  "data": [...20 products...],
  "pagination": {
    "next_cursor": "eyJpZCI6NDJ9",  // base64 encoded { "id": 42 }
    "has_more": true
  }
}

Page 2: GET /api/products?limit=20&cursor=eyJpZCI6NDJ9
SQL: SELECT * FROM products WHERE id > 42 ORDER BY id LIMIT 20

Why this is better:
  → No OFFSET — database seeks directly to id > 42 (index scan)
  → Performance is constant regardless of page number
  → Insertions don't cause duplicates (cursor is a stable pointer)

❌ BAD — Useless error:
  HTTP 400
  { "error": true }

❌ BAD — Exposes internals:
  HTTP 500
  { "error": "NullPointerException at UserService.java:142" }

✅ GOOD — Structured, actionable:
  HTTP 422
  {
    "error": {
      "code": "VALIDATION_FAILED",
      "message": "Request validation failed",
      "details": [
        {
          "field": "email",
          "message": "Must be a valid email address",
          "received": "not-an-email"
        },
        {
          "field": "age",
          "message": "Must be between 18 and 120",
          "received": -5
        }
      ],
      "request_id": "req_abc123",
      "documentation_url": "https://api.example.com/docs/errors#VALIDATION_FAILED"
    }
  }

openapi: 3.0.0
info:
  title: E-Commerce API
  version: 1.0.0

paths:
  /api/v1/products:
    get:
      summary: List products
      parameters:
        - name: cursor
          in: query
          schema: { type: string }
        - name: limit
          in: query
          schema: { type: integer, default: 20, maximum: 100 }
      responses:
        '200':
          description: Product list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/Product' }
                  pagination:
                    $ref: '#/components/schemas/CursorPagination'

components:
  schemas:
    Product:
      type: object
      required: [id, name, price]
      properties:
        id: { type: integer }
        name: { type: string }
        price: { type: number, format: double }
    CursorPagination:
      type: object
      properties:
        next_cursor: { type: string, nullable: true }
        has_more: { type: boolean }

1. VERSIONING
   Base URL: https://api.shop.com/v1
   All endpoints prefixed with /v1
   Sunset header on deprecated endpoints
   v2 runs in parallel when breaking changes are needed

2. PAGINATION (Cursor-based)
   GET /v1/products?limit=20&cursor=eyJpZCI6NDJ9
   Response includes: { data: [...], pagination: { next_cursor, has_more } }
   Default limit: 20, max limit: 100

3. IDEMPOTENCY (for mutations)
   POST /v1/orders
   Header: Idempotency-Key: order_uuid_abc123
   Server stores key → result in Redis (TTL: 24h)
   Retry with same key → returns cached result

4. ERROR HANDLING (consistent structure)
   All errors follow:
   {
     "error": {
       "code": "INSUFFICIENT_STOCK",
       "message": "Product #42 has only 3 items in stock",
       "details": [{ "field": "quantity", "message": "Requested 5, available 3" }],
       "request_id": "req_xyz789"
     }
   }

5. API CONTRACT (OpenAPI 3.0)
   Spec defined first → frontend generates TypeScript types
   Server validates requests against spec (middleware)
   Swagger UI at /docs for interactive documentation
   Contract tests run in CI to prevent drift