API Design & Versioning

Quick Navigation

Why API Design Matters for Twilio DA

The Stakes at Twilio Scale

REST API Design Principles

Resource-Oriented Design

GET    /messages           # List messages
POST   /messages           # Create message
GET    /messages/{sid}     # Get specific message
PUT    /messages/{sid}     # Update message
DELETE /messages/{sid}     # Delete message

POST /sendMessage
POST /getMessage
POST /updateMessage
POST /deleteMessage
POST /listAllMessages

HTTP Methods (Verbs)

*PATCH can be idempotent if designed carefully (e.g., "set field to X" vs "increment field")

URL Structure Best Practices

# Hierarchical resources
GET /accounts/{accountSid}/messages
GET /accounts/{accountSid}/calls/{callSid}/recordings

# Twilio pattern: Account scoping
POST /2010-04-01/Accounts/{AccountSid}/Messages.json

# Filtering via query params (not path)
GET /messages?status=delivered&dateSent>=2024-01-01

# Pagination
GET /messages?pageSize=50&pageToken=xyz123

# Sorting
GET /messages?sort=dateSent:desc

Response Design

// Successful response (200 OK)
{
  "sid": "SM123456789",
  "accountSid": "AC987654321",
  "to": "+14155551234",
  "from": "+14155556789",
  "body": "Hello, World!",
  "status": "delivered",
  "dateCreated": "2024-01-15T10:30:00Z",
  "dateUpdated": "2024-01-15T10:30:05Z",
  "uri": "/2010-04-01/Accounts/AC987654321/Messages/SM123456789.json",
  "_links": {
    "self": "/messages/SM123456789",
    "account": "/accounts/AC987654321",
    "media": "/messages/SM123456789/media"
  }
}

// Collection response with pagination
{
  "messages": [...],
  "meta": {
    "page": 0,
    "pageSize": 50,
    "totalCount": 1234,
    "pageCount": 25
  },
  "pagination": {
    "firstPageUri": "/messages?pageSize=50",
    "nextPageUri": "/messages?pageSize=50&pageToken=abc123",
    "previousPageUri": null
  }
}

Naming Conventions

Versioning Strategies

Versioning Approaches

Twilio's Date-Based Versioning

# Twilio API versions
/2010-04-01/Accounts/{AccountSid}/Messages.json  # Original version
/2020-03-15/Accounts/{AccountSid}/Messages.json  # Newer version

# Benefits:
# - Clear timeline of when features were added
# - Customer pins to specific date, knows exactly what they get
# - New versions only when breaking changes needed
# - Old versions maintained for years with deprecation warnings

Version Selection in Cell Architecture

Implementing Version Handlers

// Version-specific request/response transformers
class MessageHandlerV1 {
  // 2010-04-01: Original format
  async create(req) {
    const input = this.transformRequest(req.body);
    const result = await messageService.create(input);  // Core service
    return this.transformResponse(result);
  }

  transformRequest(body) {
    return {
      to: body.To,           // V1 uses PascalCase
      from: body.From,
      body: body.Body,
    };
  }

  transformResponse(message) {
    return {
      sid: message.id,
      To: message.to,        // V1 returns PascalCase
      From: message.from,
      Body: message.body,
      Status: message.status,
      DateCreated: message.createdAt.toISOString(),
    };
  }
}

class MessageHandlerV2 {
  // 2020-03-15: Modern format
  async create(req) {
    const input = this.transformRequest(req.body);
    const result = await messageService.create(input);  // Same core service!
    return this.transformResponse(result);
  }

  transformRequest(body) {
    return {
      to: body.to,           // V2 uses camelCase
      from: body.from,
      body: body.body,
      contentType: body.contentType,  // V2 adds new fields
      validityPeriod: body.validityPeriod,
    };
  }

  transformResponse(message) {
    return {
      sid: message.id,
      to: message.to,        // V2 returns camelCase
      from: message.from,
      body: message.body,
      status: message.status,
      dateCreated: message.createdAt,
      dateUpdated: message.updatedAt,
      _links: {              // V2 adds hypermedia
        self: `/messages/${message.id}`,
        media: `/messages/${message.id}/media`,
      },
    };
  }
}

Breaking vs Non-Breaking Changes

What Breaks Clients?

The Robustness Principle

• Servers: Accept unknown fields in requests (ignore them)
• Clients: Ignore unknown fields in responses
• Result: Both sides can evolve independently

// Server: Liberal in accepting requests
app.post('/messages', (req, res) => {
  const { to, from, body, ...unknownFields } = req.body;

  if (Object.keys(unknownFields).length > 0) {
    logger.info('Ignoring unknown fields', { fields: Object.keys(unknownFields) });
    // Don't reject! Just ignore.
  }

  // Process with known fields only
  const message = await createMessage({ to, from, body });
  res.json(message);
});

// Client: Liberal in parsing responses
function parseMessage(response) {
  // Only extract fields we know about
  // Ignore any new fields the server adds
  return {
    sid: response.sid,
    to: response.to,
    from: response.from,
    body: response.body,
    status: response.status,
    // Don't fail if response has extra fields!
  };
}

Additive-Only Evolution

Expand-Contract for Breaking Changes

Feature Flags for Gradual Rollout

// Feature flag controls new behavior
async function sendMessage(request, account) {
  const useNewValidation = await featureFlags.isEnabled(
    'sms.strict_e164_validation',
    { accountId: account.id }
  );

  if (useNewValidation) {
    // New stricter validation (potential breaking change)
    if (!isStrictE164(request.to)) {
      throw new ValidationError('Phone must be E.164 format: +1234567890');
    }
  } else {
    // Old lenient validation
    request.to = normalizeToE164(request.to);
  }

  return await messageService.send(request);
}

// Rollout strategy:
// Week 1: 1% of accounts (beta testers)
// Week 2: 10% of accounts
// Week 4: 50% of accounts
// Week 6: 100% of accounts
// Week 8: Remove flag, new behavior is default

Deprecation & Sunset Strategy

Deprecation Lifecycle

Deprecation Signals

// Response with deprecation headers
HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: true
Deprecation-Date: Wed, 01 Jan 2025 00:00:00 GMT
Sunset: Wed, 01 Jul 2025 00:00:00 GMT
Link: <https://docs.twilio.com/migration/v2>; rel="deprecation"

{
  "sid": "SM123456789",
  "Status": "sent",
  "_deprecation": {
    "warning": "API version 2010-04-01 is deprecated",
    "sunsetDate": "2025-07-01T00:00:00Z",
    "migrationGuide": "https://docs.twilio.com/migration/v2",
    "replacement": "/2024-01-01/Messages"
  }
}

Sunset Communication Timeline

Measuring Deprecation Progress

// Track deprecated endpoint usage
SELECT
  api_version,
  endpoint,
  COUNT(DISTINCT account_id) as unique_accounts,
  COUNT(*) as total_requests,
  DATE_TRUNC('week', timestamp) as week
FROM api_requests
WHERE endpoint IN (SELECT endpoint FROM deprecated_endpoints)
GROUP BY api_version, endpoint, week
ORDER BY week DESC;

// Alert if deprecated usage isn't declining
// Goal: 50% reduction each quarter until sunset

Error Handling

HTTP Status Codes

Error Response Format

// Twilio-style error response
{
  "code": 21211,
  "message": "The 'To' phone number is not a valid phone number",
  "status": 400,
  "moreInfo": "https://www.twilio.com/docs/errors/21211",
  "details": {
    "field": "to",
    "value": "not-a-phone",
    "reason": "Must be E.164 format: +1234567890"
  }
}

// Multiple validation errors
{
  "code": 20001,
  "message": "Validation failed",
  "status": 400,
  "errors": [
    {
      "field": "to",
      "code": "invalid_format",
      "message": "Must be E.164 format"
    },
    {
      "field": "body",
      "code": "too_long",
      "message": "Body exceeds 1600 characters"
    }
  ]
}

Error Code Taxonomy

Retry Guidance

// Include retry guidance in response headers
HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1699900030

{
  "code": 20429,
  "message": "Rate limit exceeded",
  "retryAfter": 30,
  "rateLimitInfo": {
    "limit": 100,
    "remaining": 0,
    "resetAt": "2024-01-15T10:30:30Z"
  }
}

// Client retry logic
async function callAPIWithRetry(request, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await makeRequest(request);
    } catch (error) {
      if (error.status === 429) {
        const retryAfter = error.headers['retry-after'] || 30;
        await sleep(retryAfter * 1000);
        continue;
      }
      if (error.status >= 500) {
        const backoff = Math.pow(2, attempt) * 1000;  // Exponential backoff
        await sleep(backoff);
        continue;
      }
      throw error;  // Don't retry 4xx errors
    }
  }
  throw new Error('Max retries exceeded');
}

Rate Limiting

Rate Limiting Strategies

Token Bucket Implementation

// Redis-based token bucket
class TokenBucket {
  constructor(redis, key, capacity, refillRate) {
    this.redis = redis;
    this.key = key;
    this.capacity = capacity;        // Max tokens (burst size)
    this.refillRate = refillRate;    // Tokens per second
  }

  async allowRequest(tokens = 1) {
    const now = Date.now();

    // Lua script for atomic operation
    const script = `
      local key = KEYS[1]
      local capacity = tonumber(ARGV[1])
      local refillRate = tonumber(ARGV[2])
      local now = tonumber(ARGV[3])
      local requested = tonumber(ARGV[4])

      local bucket = redis.call('HMGET', key, 'tokens', 'lastRefill')
      local tokens = tonumber(bucket[1]) or capacity
      local lastRefill = tonumber(bucket[2]) or now

      -- Refill tokens based on time elapsed
      local elapsed = (now - lastRefill) / 1000
      tokens = math.min(capacity, tokens + (elapsed * refillRate))

      if tokens >= requested then
        tokens = tokens - requested
        redis.call('HMSET', key, 'tokens', tokens, 'lastRefill', now)
        redis.call('EXPIRE', key, 3600)
        return {1, tokens}  -- Allowed, remaining tokens
      else
        return {0, tokens}  -- Denied, remaining tokens
      end
    `;

    const [allowed, remaining] = await this.redis.eval(
      script, 1, this.key,
      this.capacity, this.refillRate, now, tokens
    );

    return { allowed: allowed === 1, remaining };
  }
}

Rate Limit Tiers

Rate Limit Headers

// Standard rate limit headers
HTTP/1.1 200 OK
X-RateLimit-Limit: 100         // Max requests in window
X-RateLimit-Remaining: 87      // Requests left in window
X-RateLimit-Reset: 1699900060  // Unix timestamp when window resets

// Draft IETF standard (RateLimit header)
RateLimit-Limit: 100
RateLimit-Remaining: 87
RateLimit-Reset: 60            // Seconds until reset

// Twilio adds endpoint-specific limits
X-Twilio-Concurrent-Requests: 25
X-Twilio-Concurrent-Requests-Limit: 100

API Governance at Scale

The Challenge

Governance Model

API Design Standards Document

OpenAPI Linting in CI/CD

# .github/workflows/api-lint.yml
name: API Lint

on:
  pull_request:
    paths:
      - 'api/**/*.yaml'

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Lint OpenAPI Spec
        uses: stoplightio/spectral-action@v0.8
        with:
          file_glob: 'api/**/*.yaml'
          spectral_ruleset: '.spectral.yaml'

      - name: Check Breaking Changes
        run: |
          # Compare with main branch
          oasdiff breaking api/spec.yaml main:api/spec.yaml

      - name: Security Scan
        run: |
          # Check for sensitive data in examples
          # Check auth requirements on all endpoints
          api-security-scanner api/spec.yaml

Spectral Ruleset Example

# .spectral.yaml - API linting rules
extends: spectral:oas

rules:
  # Naming conventions
  paths-kebab-case:
    description: Paths must use kebab-case
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: "^(/[a-z0-9-]+)+$"

  properties-camel-case:
    description: Properties must use camelCase
    given: $..properties[*]~
    then:
      function: casing
      functionOptions:
        type: camel

  # Security
  operation-security-defined:
    description: All operations must have security defined
    given: $.paths[*][*]
    then:
      field: security
      function: truthy

  # Documentation
  operation-description:
    description: Operations must have descriptions
    given: $.paths[*][*]
    then:
      field: description
      function: truthy

  # Error responses
  error-response-schema:
    description: 4xx/5xx must use standard error schema
    given: $.paths[*][*].responses[?(@property >= 400)]
    then:
      field: content.application/json.schema.$ref
      function: pattern
      functionOptions:
        match: "#/components/schemas/Error"

API Review Board

Twilio API Patterns

Twilio API Design Philosophy

• REST-like with pragmatic exceptions: Resources are nouns, but some actions don't fit (e.g., POST /Calls/{sid}/Recordings to start recording)
• Date-based versioning: /2010-04-01/ in URL path
• Account scoping: All resources under /Accounts/{AccountSid}/
• SID identifiers: Prefixed unique IDs (SM, CA, AC)
• Webhooks as first-class: Request/response webhooks for async events

TwiML: Domain-Specific Language

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say voice="alice">Hello! Thanks for calling.</Say>
    <Gather input="speech dtmf" timeout="3" numDigits="1">
        <Say>Press 1 for sales, or 2 for support.</Say>
    </Gather>
    <Say>We didn't receive any input. Goodbye!</Say>
</Response>

Webhook Pattern

Idempotency in Twilio APIs

// Idempotency key prevents duplicate sends
POST /2010-04-01/Accounts/{AccountSid}/Messages.json
Idempotency-Key: unique-request-id-12345
Content-Type: application/x-www-form-urlencoded

To=+15551234567&From=+15559876543&Body=Hello!

// If network fails and client retries with same key:
// - First request: Message created, returns 201
// - Retry: Same response returned, no duplicate message sent

// Twilio stores idempotency keys for 24 hours

API Versioning at Landing Zone

SDK Versioning Strategy

// SDK hides API versioning from developers
const twilio = require('twilio')(accountSid, authToken);

// SDK internally uses /2020-03-15/Accounts/...
const message = await twilio.messages.create({
  to: '+15551234567',
  from: '+15559876543',
  body: 'Hello from Twilio!'
});

// To use a different API version:
const twilio = require('twilio')(accountSid, authToken, {
  apiVersion: '2024-01-01'  // Override default
});

Interview Q&A

Design Questions

Quick Reference: Key Numbers

Key Takeaways