building-api-gateway

name	building-api-gateway
description	Create API gateways with routing, load balancing, rate limiting, and authentication. Use when routing and managing multiple API services. Trigger with phrases like "build API gateway", "create API router", or "setup API gateway".
allowed-tools	Read, Write, Edit, Grep, Glob, Bash(api:gateway-*)
version	1.24.0
author	Jeremy Longshore <[e-mail]>
license	MIT
tags	["api","authentication","api-gateway"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

Building API Gateway

Overview

Create an API gateway that provides unified entry point routing, load balancing, authentication enforcement, rate limiting, request transformation, and response aggregation across multiple backend microservices. Support path-based and header-based routing, circuit breaker protection for downstream services, and centralized cross-cutting concern management.

Prerequisites

• Multiple backend API services with known endpoints, health check URLs, and authentication requirements
• Gateway framework: Express Gateway, Kong (declarative config), KrakenD, or custom Node.js/Go implementation
• Service registry or static upstream configuration for backend service discovery
• TLS certificates for gateway termination and optional mTLS for backend communication
• Centralized logging and metrics collection for gateway-level observability

Instructions

1. Inventory all backend services using Read and Grep, documenting their base URLs, endpoint paths, authentication requirements, and health check endpoints.
2. Define routing rules that map public-facing URL patterns to backend service endpoints: path-based (/users/* -> user-service), header-based (X-API-Version: 2 -> v2-service), or method-based routing.
3. Implement authentication at the gateway layer: validate JWT tokens, API keys, or OAuth2 tokens once at the gateway and forward authenticated user context to backend services via headers (X-User-ID, X-User-Roles).
4. Add rate limiting at the gateway level with per-consumer quotas, applying limits before requests reach backend services to protect all downstream services uniformly.
5. Configure request transformation: strip internal headers from incoming requests, add correlation IDs, rewrite URL paths for backend routing, and inject service-specific headers.
6. Implement response aggregation for composite endpoints that fan out to multiple backend services, merge responses, and return a unified payload to the client.
7. Add circuit breaker protection per backend service: open the circuit after configurable failure thresholds, return 503 with the failed service identified, and auto-recover after health check success.
8. Configure health check aggregation: gateway /health endpoint reports overall status based on individual backend service health, with degraded state support for non-critical service failures.
9. Write integration tests covering routing correctness, auth enforcement, rate limiting, circuit breaker behavior, and response aggregation.

See ${CLAUDE_SKILL_DIR}/references/implementation.md for the full implementation guide.