API as a product

'Missing API key');

const consumer = await redis.hGetAll(consumer:${apiKey}); if (!consumer.consumerId) throw new Error('Invalid or revoked API key');

return { apiKey, tier: consumer.tier as ConsumerTier, consumerId: consumer.consumerId, }; }

async function enforceRateLimit(ctx: ConsumerContext, endpoint: string): Promise<void> { const limit = TIER_LIMITS[ctx.tier].rpm; const key = ratelimit:${ctx.consumerId}:${endpoint}:${Date.now() / 60000}; const current = await redis.incr(key); await redis.expire(key, 60); if (current > limit) { throw new Error('Rate limit exceeded'); } }

export const productizedApiMiddleware = async (req: Request, res: Response, next: NextFunction) => { try { const ctx = await resolveConsumer(req); req.context = ctx;

const routeVersion = req.path.match(/\/v(\d+)\//)?.[1];
if (routeVersion && routeVersion !== '1') {
  return res.status(410).json({ error: 'Deprecated version', deprecation_notice: 'Use /v1/' });
}

await enforceRateLimit(ctx, req.method + req.path);

const payloadSize = req.headers['content-length'] 
  ? parseInt(req.headers['content-length'], 10) 
  : 0;
if (payloadSize > TIER_LIMITS[ctx.tier].maxPayload) {
  return res.status(413).json({ error: 'Payload too large for your tier' });
}

next();

} catch (err) { res.status(401).json({ error: err instanceof Error ? err.message : 'Authentication failed' }); } };

### Architecture Decisions & Rationale
- **Gateway-First Enforcement:** Rate limiting, tier resolution, and version routing belong in the gateway, not business logic. This keeps internal services clean and allows independent scaling of consumer-facing infrastructure.
- **Contract-First Workflow:** OpenAPI 3.1 serves as the single source of truth. Mock servers enable parallel frontend/backend development. Contract tests in CI/CD prevent silent breaking changes.
- **Consumer Identity Decoupling:** API keys are mapped to consumer profiles in a dedicated service. This enables tier upgrades, key rotation, and usage analytics without touching core business logic.
- **Telemetry-Driven SLAs:** Consumer-level metrics (latency, error rate, quota consumption) are tagged with `consumerId` and `tier`. This enables precise SLA reporting and automated overage notifications.
- **Deprecation as Code:** Version sunset policies are defined in configuration, not tribal knowledge. Automated pipeline steps generate migration guides, update portal docs, and enforce HTTP 410 responses after grace periods.

## Pitfall Guide

### 1. Exposing Internal Data Models Directly
Internal services optimize for database efficiency, not external consumption. Exposing ORM entities or internal DTOs leaks implementation details, creates tight coupling, and forces consumers to handle internal validation rules. 
**Best Practice:** Maintain a separate external contract layer. Use DTOs or projection models that map internal state to consumer-friendly shapes. Never expose internal IDs, audit fields, or service-specific metadata.

### 2. Skipping Semantic Versioning & Deprecation Windows
Treating `v1` as permanent or using date-based versions creates migration chaos. Consumers cannot plan upgrades without explicit sunset dates.
**Best Practice:** Use major versioning in the path (`/v1/resource`). Define a minimum 90-day deprecation window. Publish migration guides with code examples. Automate HTTP 410 responses after the window expires.

### 3. Hardcoding Authentication Instead of Using Centralized Key Management
Embedding API key validation in business logic creates security debt and prevents tier upgrades without code deployments.
**Best Practice:** Offload authentication to a dedicated consumer management service or API gateway. Support OIDC for enterprise consumers and API keys for programmatic access. Implement key rotation, revocation, and scoped permissions.

### 4. Ignoring Developer Experience & Sandbox Environments
Consumers abandon APIs that require manual onboarding, lack documentation, or force production data usage during development.
**Best Practice:** Ship a self-service portal with instant key provisioning, sandbox environments with deterministic mock data, and auto-generated SDKs. Provide interactive OpenAPI docs with request/response examples and cURL snippets.

### 5. No Consumer Segmentation or Tiered Rate Limiting
Flat rate limits either starve legitimate enterprise traffic or allow sandbox abuse to impact production stability.
**Best Practice:** Implement tier-based limits at the gateway. Track usage per consumer, not per IP. Provide overage alerts and automated tier upgrade flows. Isolate high-volume consumers using dedicated throughput pools when necessary.

### 6. Treating API Launch as a One-Time Event
Publishing an API and moving on guarantees technical debt. Consumer feedback, usage patterns, and SLA violations require continuous iteration.
**Best Practice:** Assign an API product owner responsible for DX metrics, retention, and roadmap. Run quarterly consumer surveys. Monitor adoption funnels in the developer portal. Treat API releases like SaaS product updates, not internal deployments.

### 7. Missing Automated Contract Testing
Manual validation allows drift between OpenAPI specs and implementation. Breaking changes slip into production when tests are skipped.
**Best Practice:** Integrate contract testing into CI/CD. Use tools like Prism, Dredd, or OpenAPI Validator to verify responses against the spec. Fail builds on contract mismatches. Generate mock servers from the spec for consumer testing.

## Production Bundle

### Action Checklist
- [ ] Define consumer tiers: Document sandbox, developer, and enterprise segments with explicit SLAs, rate limits, and support expectations
- [ ] Establish contract-first workflow: Write OpenAPI 3.1 spec, generate mock servers, and enforce contract tests in CI/CD
- [ ] Deploy consumer management service: Implement API key provisioning, tier mapping, revocation, and usage tracking
- [ ] Implement gateway middleware: Add tier resolution, rate limiting, payload validation, and version routing at the edge
- [ ] Build developer portal: Enable self-service onboarding, sandbox access, interactive docs, and SDK generation
- [ ] Instrument consumer telemetry: Tag all requests with consumerId and tier, track latency, error rates, and quota consumption
- [ ] Automate deprecation pipeline: Configure sunset dates, migration guides, and HTTP 410 enforcement for legacy versions

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| Startup validating market fit | Sandbox-first with mock data, tiered API keys, OpenAPI 3.1 | Reduces infrastructure cost while enabling real consumer feedback | Low initial infra, moderate portal dev |
| Enterprise externalizing core services | Contract-first gateway, OIDC + API key hybrid, dedicated throughput pools | Meets compliance, SLA, and security requirements | High gateway infra, low support overhead |
| Marketplace/API monetization | Tiered pricing engine, usage-based billing, automated SDK generation | Enables revenue tracking, reduces integration friction | Moderate billing integration, high retention ROI |
| Internal-only platform APIs | Versioned internal gateway, service mesh routing, shared consumer tracking | Prevents cross-team coupling, enables platform reuse | Low cost, high internal DX improvement |

### Configuration Template
Ready-to-use OpenAPI 3.1 specification snippet with productization metadata, combined with a gateway configuration template.

```yaml
openapi: 3.1.0
info:
  title: Productized Resource API
  version: 1.0.0
  x-product-meta:
    tier: developer
    sla: 99.5
    rate_limit: 1000r/min
    deprecation_policy: 90_days
    support_channel: developer_portal
paths:
  /v1/resources:
    get:
      summary: List resources
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Resource'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
  schemas:
    Resource:
      type: object
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        status: { type: string, enum: [active, archived] }

Gateway configuration (JSON):

{
  "gateway": {
    "version_routing": "/v{major}/",
    "consumer_resolution": "header:X-API-Key",
    "tiers": {
      "sandbox": { "rpm": 60, "max_payload_kb": 1, "sla": null },
      "developer": { "rpm": 1000, "max_payload_kb": 5, "sla": "99.5" },
      "enterprise": { "rpm": 10000, "max_payload_kb": 20, "sla": "99.95" }
    },
    "deprecation": {
      "grace_period_days": 90,
      "auto_410_after": true,
      "notification_channels": ["portal_email", "webhook"]
    },
    "telemetry": {
      "consumer_tagging": true,
      "metrics_endpoint": "/metrics",
      "sla_breach_threshold": 0.5
    }
  }
}

Quick Start Guide

1. Generate the OpenAPI 3.1 spec for your primary endpoint and run prism mock spec.yaml to spin up a local sandbox server.
2. Deploy the consumer management service using the provided gateway configuration, connecting it to a Redis instance for rate limiting and key validation.
3. Run the TypeScript middleware in your API gateway, mounting it before route handlers to enforce tier resolution, rate limits, and version routing.
4. Publish the spec to your developer portal, enable self-service API key generation, and verify consumer onboarding with a cURL test against the sandbox environment.
5. Instrument your backend services with consumerId headers, deploy Prometheus/Grafana dashboards for tier-level SLA tracking, and configure the 90-day deprecation pipeline for /v1/.