zhongwei/gh-jeremylongshore-claude-code-plugins-plus-plugins-api-development-api-gateway-builder

Files

Zhongwei Li f672f67611 Initial commit

2025-11-29 18:52:18 +08:00

17 KiB

Raw Blame History

description, shortcut, category, difficulty, estimated_time, version

description	shortcut	category	difficulty	estimated_time	version
Build production-ready API gateway with intelligent routing, authentication, rate limiting, and microservice orchestration	gateway	api	advanced	3-5 hours	2.0.0

Build API Gateway

Creates enterprise-grade API gateway infrastructure that serves as the single entry point for all microservices. Implements intelligent request routing, authentication, rate limiting, load balancing, and response transformation. Supports Kong, Express Gateway, AWS API Gateway, and custom implementations.

When to Use

Use this command when:

Managing multiple microservices behind a unified API
Implementing cross-cutting concerns (auth, logging, rate limiting)
Needing request/response transformation between clients and services
Requiring API composition from multiple backend services
Implementing API versioning and backward compatibility
Building for multi-tenant SaaS applications
Enforcing consistent security policies across services

Do NOT use this command for:

Simple monolithic applications with single API
Internal service-to-service communication (use service mesh instead)
Applications with only one or two endpoints
Purely static content serving

Prerequisites

Before running this command, ensure:

Microservice architecture is defined
Service discovery mechanism is available
Authentication strategy is determined
Rate limiting requirements are specified
Monitoring infrastructure is ready

Process

Step 1: Analyze Architecture Requirements

The command examines your system architecture:

Maps all backend services and their endpoints
Identifies authentication and authorization needs
Determines rate limiting and throttling requirements
Analyzes request/response transformation needs
Plans for high availability and failover

Step 2: Generate Gateway Configuration

Creates comprehensive gateway setup:

Route definitions with path matching
Authentication middleware integration
Rate limiting rules per client/endpoint
Request/response transformation pipelines
Circuit breaker configurations

Step 3: Implement Middleware Stack

Builds layered middleware architecture:

CORS handling and preflight requests
JWT validation and OAuth2 integration
Request logging and metrics collection
Response caching strategies
Error handling and formatting

Step 4: Configure Load Balancing

Sets up intelligent traffic distribution:

Round-robin, least connections, or weighted routing
Health checking and automatic failover
Sticky sessions when required
Geographic routing for multi-region
A/B testing and canary deployments

Step 5: Deploy Monitoring & Analytics

Integrates comprehensive observability:

Request/response logging
Performance metrics and tracing
Error rate monitoring
API usage analytics
Real-time dashboards

Output Format

The command generates complete gateway infrastructure:

api-gateway/
├── src/
│   ├── gateway/
│   │   ├── server.js
│   │   ├── routes/
│   │   │   ├── router.js
│   │   │   └── service-registry.js
│   │   ├── middleware/
│   │   │   ├── authentication.js
│   │   │   ├── rate-limiter.js
│   │   │   ├── transformer.js
│   │   │   └── circuit-breaker.js
│   │   └── plugins/
│   │       ├── logging.js
│   │       └── monitoring.js
│   ├── config/
│   │   ├── gateway.config.js
│   │   ├── services.json
│   │   └── rate-limits.json
│   └── utils/
│       ├── load-balancer.js
│       └── service-discovery.js
├── kong/
│   ├── kong.yml
│   └── plugins/
├── tests/
│   └── gateway.test.js
└── docs/
    └── api-gateway-guide.md

Examples

Example 1: Express Gateway with JWT Authentication

Scenario: Microservices gateway with JWT auth and rate limiting

Generated Express Gateway Implementation:

// gateway/server.js
import express from 'express';
import httpProxy from 'http-proxy-middleware';
import jwt from 'jsonwebtoken';
import rateLimit from 'express-rate-limit';
import CircuitBreaker from 'opossum';

class APIGateway {
  constructor(config) {
    this.app = express();
    this.services = config.services;
    this.setupMiddleware();
    this.setupRoutes();
    this.setupErrorHandling();
  }

  setupMiddleware() {
    // CORS configuration
    this.app.use((req, res, next) => {
      res.header('Access-Control-Allow-Origin', process.env.ALLOWED_ORIGINS);
      res.header('Access-Control-Allow-Methods', 'GET,PUT,POST,DELETE,OPTIONS');
      res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization');
      if (req.method === 'OPTIONS') {
        return res.sendStatus(200);
      }
      next();
    });

    // Request logging
    this.app.use((req, res, next) => {
      const startTime = Date.now();
      res.on('finish', () => {
        const duration = Date.now() - startTime;
        console.log({
          method: req.method,
          path: req.path,
          status: res.statusCode,
          duration,
          ip: req.ip,
          userAgent: req.get('user-agent')
        });
      });
      next();
    });

    // Global rate limiting
    const globalLimiter = rateLimit({
      windowMs: 60 * 1000, // 1 minute
      max: 100, // 100 requests per minute
      message: 'Too many requests, please try again later',
      standardHeaders: true,
      legacyHeaders: false
    });
    this.app.use(globalLimiter);
  }

  setupRoutes() {
    // Service routes with specific configurations
    Object.entries(this.services).forEach(([name, config]) => {
      const { path, target, auth, rateLimit: limits, circuitBreaker } = config;

      // Create middleware chain for this service
      const middlewares = [];

      // Authentication middleware if required
      if (auth) {
        middlewares.push(this.createAuthMiddleware(auth));
      }

      // Service-specific rate limiting
      if (limits) {
        middlewares.push(rateLimit({
          windowMs: limits.windowMs || 60000,
          max: limits.max || 50,
          keyGenerator: (req) => {
            return req.user?.id || req.ip;
          }
        }));
      }

      // Circuit breaker for resilience
      const breaker = new CircuitBreaker(
        this.createProxyMiddleware(target),
        {
          timeout: circuitBreaker?.timeout || 3000,
          errorThresholdPercentage: circuitBreaker?.errorThreshold || 50,
          resetTimeout: circuitBreaker?.resetTimeout || 30000
        }
      );

      // Monitoring circuit breaker events
      breaker.on('open', () => {
        console.error(`Circuit breaker opened for ${name}`);
      });

      // Apply middlewares and proxy
      this.app.use(path, ...middlewares, (req, res, next) => {
        breaker.fire(req, res, next)
          .catch(err => {
            res.status(503).json({
              error: 'Service temporarily unavailable',
              service: name
            });
          });
      });
    });
  }

  createAuthMiddleware(authConfig) {
    return async (req, res, next) => {
      const token = req.headers.authorization?.split(' ')[1];

      if (!token) {
        return res.status(401).json({ error: 'No token provided' });
      }

      try {
        const decoded = jwt.verify(token, process.env.JWT_SECRET);
        req.user = decoded;

        // Check permissions if specified
        if (authConfig.requiredScopes) {
          const hasPermission = authConfig.requiredScopes.some(scope =>
            decoded.scopes?.includes(scope)
          );

          if (!hasPermission) {
            return res.status(403).json({ error: 'Insufficient permissions' });
          }
        }

        next();
      } catch (error) {
        return res.status(401).json({ error: 'Invalid token' });
      }
    };
  }

  createProxyMiddleware(target) {
    return httpProxy.createProxyMiddleware({
      target,
      changeOrigin: true,
      onProxyReq: (proxyReq, req) => {
        // Add tracing headers
        proxyReq.setHeader('X-Request-ID', req.id || uuid.v4());
        proxyReq.setHeader('X-Forwarded-For', req.ip);

        // Forward user context if authenticated
        if (req.user) {
          proxyReq.setHeader('X-User-ID', req.user.id);
          proxyReq.setHeader('X-User-Roles', JSON.stringify(req.user.roles));
        }
      },
      onProxyRes: (proxyRes, req, res) => {
        // Add response headers
        proxyRes.headers['X-Gateway-Version'] = '1.0.0';
        proxyRes.headers['X-Response-Time'] = Date.now() - req.startTime;
      }
    });
  }
}

// config/services.json
{
  "userService": {
    "path": "/api/users",
    "target": "http://user-service:3001",
    "auth": {
      "required": true,
      "requiredScopes": ["users:read", "users:write"]
    },
    "rateLimit": {
      "windowMs": 60000,
      "max": 100
    },
    "circuitBreaker": {
      "timeout": 5000,
      "errorThreshold": 50,
      "resetTimeout": 30000
    }
  },
  "productService": {
    "path": "/api/products",
    "target": "http://product-service:3002",
    "auth": {
      "required": false
    },
    "rateLimit": {
      "windowMs": 60000,
      "max": 200
    }
  }
}

Example 2: Kong Gateway Configuration

Scenario: Enterprise Kong gateway with plugins

Generated Kong Configuration:

# kong.yml
_format_version: "2.1"

services:
  - name: user-service
    url: http://user-service:3001
    routes:
      - name: user-routes
        paths:
          - /api/users
        strip_path: false
        methods:
          - GET
          - POST
          - PUT
          - DELETE
    plugins:
      - name: jwt
        config:
          key_claim_name: kid
          secret_is_base64: false
      - name: rate-limiting
        config:
          minute: 100
          hour: 10000
          policy: local
      - name: request-transformer
        config:
          add:
            headers:
              - X-Gateway:Kong
              - X-Service:user-service

  - name: product-service
    url: http://product-service:3002
    routes:
      - name: product-routes
        paths:
          - /api/products
    plugins:
      - name: rate-limiting
        config:
          minute: 200
          policy: redis
          redis_host: redis
          redis_port: 6379
      - name: cors
        config:
          origins:
            - https://app.example.com
          methods:
            - GET
            - POST
          headers:
            - Accept
            - Content-Type
          credentials: true
      - name: prometheus

upstreams:
  - name: user-service
    algorithm: round-robin
    targets:
      - target: user-service-1:3001
        weight: 100
      - target: user-service-2:3001
        weight: 100
    healthchecks:
      active:
        healthy:
          interval: 10
          successes: 3
        unhealthy:
          interval: 5
          http_failures: 3

plugins:
  - name: correlation-id
    config:
      header_name: X-Request-ID
      generator: uuid
  - name: request-size-limiting
    config:
      allowed_payload_size: 10

Example 3: API Composition and Response Aggregation

Scenario: Gateway that combines multiple service responses

Generated API Composition:

// gateway/api-composer.js
class APIComposer {
  async composeUserProfile(userId, req) {
    // Parallel requests to multiple services
    const [user, orders, preferences, recommendations] = await Promise.allSettled([
      this.fetchUser(userId, req.headers),
      this.fetchUserOrders(userId, req.headers),
      this.fetchUserPreferences(userId, req.headers),
      this.fetchRecommendations(userId, req.headers)
    ]);

    // Compose response with error handling
    const profile = {
      user: user.status === 'fulfilled' ? user.value : null,
      orders: orders.status === 'fulfilled' ? orders.value : [],
      preferences: preferences.status === 'fulfilled' ? preferences.value : {},
      recommendations: recommendations.status === 'fulfilled' ? recommendations.value : []
    };

    // Add metadata
    profile._meta = {
      composed_at: new Date().toISOString(),
      partial: Object.values(profile).some(v => v === null || v === undefined),
      services: {
        user: user.status,
        orders: orders.status,
        preferences: preferences.status,
        recommendations: recommendations.status
      }
    };

    return profile;
  }

  async fetchWithTimeout(url, options, timeout = 3000) {
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), timeout);

    try {
      const response = await fetch(url, {
        ...options,
        signal: controller.signal
      });
      clearTimeout(timeoutId);
      return response.json();
    } catch (error) {
      clearTimeout(timeoutId);
      throw error;
    }
  }
}

Error Handling

Error: Service Unavailable

Symptoms: 503 errors, timeouts Cause: Backend service down or overloaded Solution:

// Implement circuit breaker and fallback
breaker.fallback(() => ({
  data: [],
  source: 'cache',
  message: 'Using cached data due to service unavailability'
}));

Prevention: Health checks, circuit breakers, graceful degradation

Error: Authentication Failures

Symptoms: High rate of 401/403 errors Cause: Token expiry, invalid credentials, or permission issues Solution: Implement token refresh mechanism and clear error messages

Error: Rate Limit Exceeded

Symptoms: 429 Too Many Requests Cause: Client exceeding configured limits Solution: Implement backoff strategy and provide rate limit headers

Configuration Options

Option: `--framework`

Purpose: Choose gateway framework
Values: kong, express-gateway, custom, aws-api-gateway
Default: custom
Example: /gateway --framework kong

Option: `--auth`

Purpose: Authentication method
Values: jwt, oauth2, api-key, basic, none
Default: jwt
Example: /gateway --auth oauth2

Option: `--load-balancer`

Purpose: Load balancing algorithm
Values: round-robin, least-connections, weighted, ip-hash
Default: round-robin
Example: /gateway --load-balancer weighted

Best Practices

✅ DO:

Implement circuit breakers for all backend services
Use correlation IDs for request tracing
Cache responses where appropriate
Monitor gateway performance metrics
Implement graceful degradation strategies

❌ DON'T:

Perform heavy business logic in the gateway
Store state in the gateway (keep it stateless)
Ignore security headers and CORS configuration
Mix internal and external APIs on same gateway

💡 TIPS:

Use API composition sparingly to avoid gateway bottleneck
Implement request/response transformation close to services when possible
Consider GraphQL gateway for complex data aggregation needs
Use service mesh for internal service communication

/api-rate-limiter - Dedicated rate limiting setup
/api-monitoring-dashboard - Gateway monitoring
/service-mesh-configurator - Internal service communication
/load-balancer-configurator - Advanced load balancing

Performance Considerations

Latency overhead: 5-20ms per request typically
Memory usage: ~200MB base + 10MB per 1000 concurrent connections
CPU usage: Scales linearly with request rate
Network: Consider gateway placement for minimal hops

Security Notes

⚠️ Security Considerations:

Always use HTTPS/TLS for external traffic
Implement DDoS protection at gateway level
Validate and sanitize all incoming requests
Never log sensitive data (tokens, passwords)
Use API key rotation and token expiration

Troubleshooting

Issue: High gateway latency

Solution: Check service response times, reduce middleware chain, enable caching

Issue: Memory leaks

Solution: Monitor event listeners, implement proper cleanup, limit request body size

Issue: Inconsistent routing

Solution: Review route precedence, check path matching patterns

Getting Help

Kong documentation: https://docs.konghq.com
Express Gateway: https://www.express-gateway.io/docs
API Gateway patterns: https://microservices.io/patterns/apigateway.html

Version History

v2.0.0 - Complete rewrite with multiple framework support and API composition
v1.0.0 - Initial Express-only implementation

Last updated: 2025-10-11 Quality score: 9.5/10 Tested with: Kong 2.8, Express Gateway 1.16, Node.js 18

17 KiB Raw Blame History