What are API gateway patterns and when should I use them?

They are structured approaches for routing, security, traffic management, and composition in microservices. Use them when building API gateways, BFF layers, or managing cross-service communication at scale.

How do I choose between a Single Gateway, BFF, GraphQL gateway, or a service mesh?

Choose based on client diversity, performance needs, and team structure: Single gateway for simplicity, BFF for client-optimized gateways, GraphQL for flexible data fetching, and a service mesh for distributed gateway capabilities.

What are the core components I should implement at the gateway?

Routing rules, centralized security (authz/auth), traffic management (rate limiting, circuit breakers, retries), API transformation/aggregation, and observability (tracing and metrics).

api-gateway-patterns

npx machina-cli add skill NickCrew/claude-cortex/api-gateway-patterns --openclaw

Files (1)

SKILL.md

6.2 KB

API Gateway Patterns

Expert guidance for implementing API gateways with routing, authentication, traffic management, and service composition patterns for microservices architectures at scale.

When to Use This Skill

Implementing API gateway infrastructure for microservices
Designing Backend for Frontend (BFF) layers
Adding authentication and authorization at the gateway level
Implementing rate limiting, circuit breakers, and retry logic
Setting up service discovery and dynamic routing
Building API composition and aggregation layers
Managing cross-cutting concerns (logging, monitoring, CORS)
Evaluating gateway solutions (Kong, Nginx, Envoy, AWS API Gateway)

Core Concepts

Gateway Responsibilities

Routing: Direct requests to appropriate backend services based on path, headers, or host Security: Centralized authentication, authorization, and API key validation Traffic Management: Rate limiting, circuit breakers, retry logic Composition: Aggregate multiple service calls into unified responses Transformation: Modify requests/responses for client optimization or legacy adaptation

Architecture Patterns

Single Gateway: One gateway for all clients (simple, potential bottleneck) BFF Pattern: Separate gateway per client type (mobile, web, admin) - optimized for each GraphQL Gateway: Schema stitching across services, client-driven data fetching Service Mesh: Distributed gateway pattern with sidecar proxies (Istio, Linkerd)

Quick Reference

Task	Load reference
Routing strategies (path, header, host-based)	`skills/api-gateway-patterns/references/routing-patterns.md`
Request/response transformation	`skills/api-gateway-patterns/references/transformation.md`
API composition and aggregation	`skills/api-gateway-patterns/references/composition.md`
Authentication & authorization (JWT, OAuth, RBAC)	`skills/api-gateway-patterns/references/authentication.md`
Traffic management (rate limiting, circuit breakers)	`skills/api-gateway-patterns/references/traffic-management.md`
Backend for Frontend (BFF) pattern	`skills/api-gateway-patterns/references/bff-pattern.md`
Service discovery integration	`skills/api-gateway-patterns/references/service-discovery.md`
Gateway implementations (Kong, Nginx, Envoy, AWS)	`skills/api-gateway-patterns/references/implementations.md`

Implementation Workflow

Phase 1: Requirements Analysis

Identify client types: Mobile, web, admin, partners
Map service landscape: Catalog backend services and endpoints
Define cross-cutting concerns: Auth, logging, monitoring, CORS
Determine composition needs: Which endpoints require aggregation?
Establish SLAs: Latency, throughput, availability targets

Phase 2: Gateway Design

Choose architecture: Single gateway vs BFF vs GraphQL
Select implementation: Kong, Nginx, Envoy, AWS API Gateway
Design routing rules: Path-based, header-based, host-based
Plan authentication: JWT, OAuth 2.0, API keys, or hybrid
Define traffic policies: Rate limits, circuit breakers, timeouts

Phase 3: Implementation

Set up infrastructure: Deploy gateway instances, configure load balancer
Implement routing: Configure service discovery and route definitions
Add authentication: JWT validation, OAuth integration, API key management
Apply traffic management: Rate limiting, circuit breakers, retry logic
Enable observability: Distributed tracing, metrics, structured logging

Phase 4: Testing & Optimization

Load testing: Verify performance under expected and peak load
Failure injection: Test circuit breakers and retry logic
Security testing: Verify auth flows, token validation, RBAC policies
Latency optimization: Cache strategies, connection pooling
Monitor and tune: Adjust timeouts, limits based on real traffic

Best Practices

Centralize Cross-Cutting Concerns: Authentication, logging, monitoring at gateway
Keep Gateway Lightweight: Avoid complex business logic, delegate to services
Implement Health Checks: Monitor upstream service health, remove unhealthy instances
Use Circuit Breakers: Prevent cascading failures, fail fast
Apply Rate Limiting: Protect services from overload, implement tiered limits
Enable Observability: Distributed tracing, metrics, structured logging
Version APIs: Support multiple API versions, plan deprecation
Secure Communication: TLS everywhere, mutual TLS for service-to-service
Cache Strategically: Response caching, but invalidate properly
Test Resilience: Chaos engineering, failure injection, load testing

Common Mistakes

Business Logic in Gateway: Keep gateway focused on routing/security, not business rules
Chatty Composition: Too many upstream calls (use BFF, GraphQL, or caching)
Single Point of Failure: Deploy redundantly, use load balancers
No Timeout Configuration: Always set connection/read timeouts to prevent hanging requests
Ignoring Backpressure: Implement queue limits, graceful degradation
Over-Aggregation: Don't make gateway do too much work (compute-heavy transformations)
Inadequate Monitoring: Must track latency, errors, throughput at gateway level
No Rate Limiting: Services will be overwhelmed eventually without protection
Synchronous Everything: Use async patterns for non-critical operations
No Version Strategy: Breaking changes break all clients simultaneously

Resources

Kong: https://docs.konghq.com/gateway/latest/
Nginx: https://nginx.org/en/docs/
Envoy: https://www.envoyproxy.io/docs/envoy/latest/
AWS API Gateway: https://docs.aws.amazon.com/apigateway/
Patterns: "Microservices Patterns" by Chris Richardson
Service Mesh: https://istio.io/latest/docs/
Circuit Breakers: Martin Fowler's CircuitBreaker pattern
BFF Pattern: Sam Newman's "Building Microservices"

Source

git clone https://github.com/NickCrew/claude-cortex/blob/main/skills/api-gateway-patterns/SKILL.mdView on GitHub

Overview

API gateway patterns provide structured approaches to route requests, enforce security, manage traffic, and aggregate responses across microservices. This skill helps you design gateway architectures (Single gateway, BFF, GraphQL, or service mesh), apply cross-cutting concerns, and operate at scale.

How This Skill Works

Gateways centralize routing, security, and traffic policies while performing transformation and composition. They implement architecture patterns such as Single Gateway, BFF-specific gateways, GraphQL gateways, or service meshes, using tools like Kong, Nginx, Envoy, or AWS API Gateway, with a lifecycle from requirements analysis through testing.

When to Use It

Implementing API gateway infrastructure for microservices
Designing Backend for Frontend (BFF) layers
Adding authentication and authorization at the gateway level
Implementing rate limiting, circuit breakers, and retry logic
Setting up service discovery and dynamic routing

Quick Start

Step 1: Set up gateway infrastructure and choose an architecture (Single, BFF, GraphQL, or service mesh) and a load balancer.
Step 2: Define routing rules (path/header/host) and connect services via service discovery; configure basic transformation rules.
Step 3: Enable authentication (JWT/OAuth/API keys), apply traffic policies (rate limits, retries, circuit breakers), and turn on observability (tracing, metrics).

Best Practices

Start with a detailed requirements/landscape: identify client types, catalog backend services, and define cross-cutting concerns (auth, logging, CORS).
Choose an architecture that fits your needs (Single gateway for simplicity, BFF per client type, GraphQL gateway, or a service mesh).
Define explicit routing rules and early decisions on transformation and composition for each endpoint.
Plan robust security and traffic policies (JWT/OAuth/API keys, rate limits, timeouts, circuit breakers) before implementation.
Build for observability: trace requests, collect metrics, and ensure consistent logging across gateways.

Example Use Cases

A mobile app uses a dedicated BFF gateway that optimizes payloads and aggregates data for mobile clients.
A GraphQL gateway stitches schemas from catalog, pricing, and reviews services to serve UI needs with a single endpoint.
Kong or Envoy-based gateway enforces JWT/OAuth at the edge and centralizes API key validation for backend services.
A service-mesh approach with Istio/Linkerd provides distributed gateway capabilities with sidecar proxies.
An API composition layer aggregates multiple microservice calls into a single response to reduce client calls.

Frequently Asked Questions

Add this skill to your agents