API Case Study

# WHAT: APIForge version negotiation — header-based versioning
# Request with explicit version header (testing a newer version)
# Without the header, the server falls back to the version pinned to the API key

GET /api/projects HTTP/1.1
Host: api.apiforge.dev
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...
APIForge-Version: 2024-09-01

# Server reads version priority:
# 1. APIForge-Version header (if present)
# 2. Version pinned to the API key at creation time
# 3. Fallback: current stable version

// WHAT: APIForge error response builder — Stripe-style structured errors
// File: src/utils/apiError.js
// Every error in the API goes through this builder for consistency

function buildError({ type, message, code, param = null, statusCode }) {
  return {
    statusCode,
    body: {
      error: {
        type,
        message,
        code,
        param,
        doc_url: `https://docs.apiforge.dev/errors/${code}`,
        request_id: generateRequestId(), // unique ID per request for support lookups
      }
    }
  };
}

// Usage examples across the API:

// Missing required field
buildError({
  type:       'invalid_request_error',
  message:    'The project name is required and cannot be blank.',
  code:       'parameter_missing',
  param:      'name',
  statusCode: 400,
});

// Resource not found
buildError({
  type:       'invalid_request_error',
  message:    'No such project: proj_xyz99',
  code:       'resource_missing',
  param:      'id',
  statusCode: 404,
});

// Authentication failure
buildError({
  type:       'authentication_error',
  message:    'No valid API key provided.',
  code:       'api_key_missing',
  param:      null,
  statusCode: 401,
});

// WHAT: APIForge idempotency key implementation
// File: src/middleware/idempotency.js
// Stores request results in Redis keyed by Idempotency-Key header
// Applies to POST and PATCH routes only — GET and DELETE are already idempotent

import Redis from 'ioredis';
const redis = new Redis(process.env.REDIS_URL);
const TTL   = 60 * 60 * 24; // 24 hours — same as Stripe

export async function idempotency(req, res, next) {
  // Only applies to state-changing methods
  if (!['POST', 'PATCH'].includes(req.method)) return next();

  const key = req.headers['idempotency-key'];
  if (!key) return next(); // Key is optional — no key means no protection

  const cacheKey = `idempotency:${req.user.userId}:${key}`;

  // Check if we have a stored response for this key
  const cached = await redis.get(cacheKey);
  if (cached) {
    const { statusCode, body } = JSON.parse(cached);
    res.setHeader('Idempotency-Replayed', 'true');
    return res.status(statusCode).json(body);
  }

  // Intercept the response to store it before sending
  const originalJson = res.json.bind(res);
  res.json = async (body) => {
    // Only cache successful responses and known errors (not 5xx)
    if (res.statusCode < 500) {
      await redis.setEx(
        cacheKey,
        TTL,
        JSON.stringify({ statusCode: res.statusCode, body })
      );
    }
    return originalJson(body);
  };

  next();
}

# WHAT: APIForge cursor pagination — Stripe-style response envelope
# Client fetches the first page, then uses starting_after to get the next

# Page 1 — no cursor
GET /api/projects?limit=3 HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

# Page 2 — use last ID from page 1 as cursor
GET /api/projects?limit=3&starting_after=proj_003 HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

// WHAT: APIForge webhook signature verification — Stripe pattern
// File: src/routes/webhooks.js
// Every incoming webhook is verified before any handler runs

import crypto from 'crypto';

const WEBHOOK_SECRET  = process.env.WEBHOOK_SECRET; // shared with webhook sender
const TOLERANCE_SECS  = 300; // reject webhooks older than 5 minutes

function verifyWebhookSignature(payload, signatureHeader) {
  // Stripe-Signature header format:
  // t=1731580800,v1=abc123def456...
  const parts     = Object.fromEntries(
    signatureHeader.split(',').map(p => p.split('='))
  );
  const timestamp = parseInt(parts['t'], 10);
  const signature = parts['v1'];

  // Reject stale webhooks (replay attack protection)
  const now = Math.floor(Date.now() / 1000);
  if (now - timestamp > TOLERANCE_SECS) {
    throw new Error('Webhook timestamp too old — possible replay attack');
  }

  // Recompute HMAC-SHA256 using raw body + timestamp
  const signedPayload = `${timestamp}.${payload}`;
  const expected = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(signedPayload)
    .digest('hex');

  if (expected !== signature) {
    throw new Error('Webhook signature mismatch — payload may be tampered');
  }

  return true;
}

// Express route — use express.raw() NOT express.json() to get raw body for HMAC
app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    verifyWebhookSignature(req.body.toString(), req.headers['apiforge-signature']);
  } catch (err) {
    return res.status(400).json({ error: err.message });
  }

  const event = JSON.parse(req.body);
  switch (event.type) {
    case 'project.created':  handleProjectCreated(event.data);  break;
    case 'member.deleted':   handleMemberDeleted(event.data);   break;
    default:
      console.log(`Unhandled event type: ${event.type}`);
  }

  res.status(200).json({ received: true }); // Always respond 200 quickly
});

// WHAT: APIForge rate limit headers — included on every response, not just 429
// File: src/middleware/rateLimitHeaders.js
// Clients use these headers to self-throttle before hitting the hard limit

// Headers sent on EVERY response:
//   X-RateLimit-Limit:      total requests allowed per window
//   X-RateLimit-Remaining:  requests left in current window
//   X-RateLimit-Reset:      unix timestamp when the window resets
//   X-RateLimit-Window:     window duration in seconds

// Header sent ONLY on 429 responses:
//   Retry-After:  seconds to wait before retrying (RFC 7231 standard)

// Example: client reads headers and self-throttles
async function apiFetch(url, options = {}) {
  const response = await fetch(url, options);

  const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
  const resetAt   = parseInt(response.headers.get('X-RateLimit-Reset'));
  const now       = Math.floor(Date.now() / 1000);

  if (remaining < 10) {
    // Fewer than 10 requests left — slow down proactively
    const waitMs = (resetAt - now) * 1000;
    console.warn(`Rate limit low (${remaining} left). Pausing ${waitMs}ms.`);
    await new Promise(resolve => setTimeout(resolve, waitMs));
  }

  if (response.status === 429) {
    const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
    console.error(`Rate limited. Retrying in ${retryAfter}s.`);
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    return apiFetch(url, options); // retry once after waiting
  }

  return response;
}