❌ Verb-oriented (RPC disguised as HTTP):
POST /getOrder?orderId=42
POST /cancelOrder
GET  /createPayment

✅ Resource-oriented (REST):
GET    /orders/42
POST   /orders/42/cancellations
POST   /payments

GET    /orders/42       → Safe + Idempotent. No side effects. Identical response every time (given stable state).
POST   /orders          → Neither safe nor idempotent. Creates a new resource. Response includes Location header.
PUT    /orders/42       → Idempotent (not safe). Replaces entire resource. Repeated calls produce same result.
PATCH  /orders/42       → Idempotent only when deterministic. Partial update.
DELETE /orders/42       → Idempotent (not safe). Repeated deletes return 404 after first success — that is correct behavior.

// ❌ PATCH used as a relative increment — NOT idempotent
PATCH /inventory/SKU-001
{ "adjustQuantity": -5 }
// Calling this twice reduces quantity by 10. Retrying a failed request causes data corruption.

// ✅ PATCH used as a deterministic set — IS idempotent
PATCH /inventory/SKU-001
{ "quantityOnHand": 45 }
// Calling this twice produces the same result: quantityOnHand = 45

// ✅ PUT for full replacement — always idempotent
PUT /inventory/SKU-001
{
  "sku": "SKU-001",
  "quantityOnHand": 45,
  "reorderPoint": 10,
  "warehouseId": "WH-NYC-01"
}
// PUT requires ALL fields. Omitting a field implies its removal (or reset to default).

// ✅ POST creates a new resource — response MUST include Location header
POST /orders
Content-Type: application/json
{
  "userId": "usr_abc",
  "items": [{ "sku": "SKU-001", "quantity": 2 }]
}

// Response:
HTTP/1.1 201 Created
Location: /orders/ord_xyz789
Content-Type: application/json
{
  "id": "ord_xyz789",
  "status": "pending",
  "createdAt": "2026-09-06T17:43:00Z"
}

400 Bad Request        → Malformed syntax. The request body is not parseable JSON, or a required field is missing entirely.
401 Unauthorized       → No credentials or expired token. Client must re-authenticate before retrying.
403 Forbidden          → Valid credentials, insufficient permissions. Retrying with the same token will never succeed.
404 Not Found          → Resource does not exist. Client must not retry — the resource is gone.
409 Conflict           → State conflict. Duplicate creation attempt, optimistic lock failure (ETag mismatch), or state machine violation.
422 Unprocessable      → Syntactically valid but semantically invalid. endDate < startDate, quantity > stockLevel, etc.
429 Too Many Requests  → Rate limit exceeded. Client MUST respect Retry-After header.

// ❌ Ad-hoc error body — clients must parse free-text strings
HTTP/1.1 422 Unprocessable Entity
{
  "error": "Invalid date range",
  "message": "The end date cannot be before the start date"
}
// Branching on this requires string matching — fragile and untranslatable

// ✅ RFC 7807 Problem Details — machine-readable, extensible
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json
{
  "type": "https://api.example.com/problems/invalid-date-range",
  "title": "Invalid Date Range",
  "status": 422,
  "detail": "The checkout endDate (2026-01-01) must be after startDate (2026-03-01).",
  "instance": "/orders/ord_xyz789/checkout",
  "errors": [
    {
      "field": "endDate",
      "code": "DATE_BEFORE_START",
      "value": "2026-01-01"
    }
  ]
}

// ❌ Offset pagination — inconsistent under concurrent inserts
GET /orders?offset=100&limit=20

// Problem: Between page 5 and page 6, a new order is inserted at position 100.
// Page 5 returned items 100–119.
// Page 6 now returns items 120–139 — but the item that WAS at 120 shifted to 121.
// Item at OLD position 120 (now 121) appears on BOTH page 5 and page 6.
// Item at OLD position 119 is skipped entirely.
// This is a silent data integrity bug, invisible to the client.

// ✅ Cursor pagination — stable under concurrent mutations
GET /orders?limit=20
// Response:
{
  "data": [...],
  "pagination": {
    "nextCursor": "eyJpZCI6Im9yZF8xMjMiLCJjcmVhdGVkQXQiOiIyMDI2LTA5LTA2In0=",
    "hasMore": true
  }
}

// Next page:
GET /orders?limit=20&cursor=eyJpZCI6Im9yZF8xMjMiLCJjcmVhdGVkQXQiOiIyMDI2LTA5LTA2In0=

-- ✅ Keyset pagination — uses the index directly, O(log n) regardless of page number
SELECT id, title, created_at
FROM orders
WHERE created_at < '2026-09-06T17:43:00Z'
   OR (created_at = '2026-09-06T17:43:00Z' AND id < 'ord_xyz789')
ORDER BY created_at DESC, id DESC
LIMIT 21;
-- Fetch 21 to detect hasMore; return 20 to the client

-- ❌ Offset query — O(n) full scan grows with page depth
SELECT id, title, created_at
FROM orders
ORDER BY created_at DESC
OFFSET 10000 LIMIT 20;
-- At offset 10,000: PostgreSQL scans 10,000 rows to throw them away. At offset 1,000,000: it scans 1,000,000.

// ✅ Non-breaking changes (safe to ship without version bump)
// - Adding new optional fields to responses
// - Adding new optional fields to request bodies
// - Adding new endpoints
// - Adding new enum values (if clients ignore unknown values)

// ❌ Breaking changes (require version bump)
// - Removing fields from responses
// - Renaming fields
// - Changing field types (string → number)
// - Changing required/optional status of request fields
// - Changing status codes for existing conditions
// - Removing endpoints

// ✅ OpenAPI 3.1 deprecation pattern:
{
  "userId": {
    "type": "string",
    "description": "User identifier",
    "deprecated": true,
    "x-deprecation-reason": "Use accountId instead. userId will be removed in v3 (2027-01-01)."
  },
  "accountId": {
    "type": "string",
    "description": "Account identifier — replaces userId"
  }
}

GET /orders?status=shipped&createdAfter=2026-09-01T00:00:00Z&sort=-createdAt,id&fields=id,status,totalCents

# Filtering:  ?status=shipped&createdAfter=2026-09-01T00:00:00Z
# Sorting:    ?sort=-createdAt,id     (- prefix = descending)
# Sparse:     ?fields=id,status,totalCents  (reduces response payload)

# openapi.yaml — schema-first, validated in CI
openapi: "3.1.0"
info:
  title: Orders API
  version: "1.0.0"
paths:
  /orders:
    get:
      operationId: listOrders
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, processing, shipped, delivered, cancelled]
        - name: sort
          in: query
          schema:
            type: string
            pattern: "^-?(createdAt|updatedAt|totalCents)(,-?(createdAt|updatedAt|totalCents))*$"
        - name: cursor
          in: query
          schema:
            type: string
            description: Opaque pagination cursor from previous response
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrderListResponse"
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"

// CI gate: validate all request/response bodies against the OpenAPI schema
import { OpenApiValidator } from 'express-openapi-validator'

app.use(
  OpenApiValidator.middleware({
    apiSpec: './openapi.yaml',
    validateRequests: true,
    validateResponses: true, // Catch response schema violations in test/staging
  })
)
// Any response that violates the schema in staging fails the build.
// This is the only reliable way to prevent accidental breaking changes.