| name | api-gateway-builder |
| description | Expert guide for designing and configuring API gateways including Kong, AWS API Gateway, and cloud-native solutions. Covers rate limiting, authentication, routing, throttling, request transformation, caching, and production deployment patterns.
Use when the user asks about api gateway builder, api gateway builder best practices, or needs guidance on api gateway builder implementation.
Do NOT use when the user needs a different specialized skill or is asking about an unrelated technology domain.
|
| license | Apache-2.0 |
| metadata | {"author":"foundry-skills","version":"1.0.0","tags":"backend api-design guide","category":"backend-systems","subcategory":"api-design","depends":"","disclaimer":"none","difficulty":"advanced"} |
API Gateway Builder
You are an expert in designing and operating API gateway infrastructure. You guide teams through gateway selection, routing configuration, rate limiting, authentication integration, request/response transformation, and production operations for both self-managed and cloud-native API gateways.
Core Principles
- Gateway is the front door - It handles cross-cutting concerns so services do not have to.
- Fail open vs fail closed - Authentication must fail closed; rate limiting can fail open under extreme load.
- Keep the gateway thin - Route, authenticate, rate limit, transform. Never put business logic in the gateway.
Gateway Selection
GATEWAY TYPE BEST FOR COST MODEL
---------------------------------------------------------------------------
AWS API GW (HTTP) Managed Serverless, low complexity $1/million reqs
AWS API GW (REST) Managed WebSocket, caching, WAF $3.50/million
Kong Self-managed Multi-cloud, plugins, K8s Open source/EE
Envoy / Istio Self-managed Service mesh, gRPC Free (infra cost)
Traefik Self-managed Docker/K8s auto-discovery Open source/EE
NGINX Self-managed Max performance, mature Open source/Plus
CHOOSE AWS API GW: Serverless backend, AWS-native, <10K req/s
CHOOSE KONG: Multi-cloud, complex plugins, Kubernetes-native
CHOOSE ENVOY: Service mesh, gRPC-native, fine-grained traffic control
CHOOSE NGINX: Maximum raw performance, simple routing needs
Kong Configuration
Declarative Config (kong.yml)
_format_version: "3.0"
services:
- name: user-service
url: [reference URL]
connect_timeout: 5000
read_timeout: 30000
retries: 3
routes:
- name: user-routes
paths: [/api/v1/users]
methods: [GET, POST, PUT, DELETE]
strip_path: false
protocols: [https]
plugins:
- name: rate-limiting
config:
minute: 100
hour: 5000
policy: redis
redis_host: redis
fault_tolerant: true
- name: correlation-id
config:
header_name: X-Request-ID
generator: uuid
echo_downstream:
Service-Level Plugins
plugins:
- name: rate-limiting
route: login-route
config:
minute: 10
- name: jwt
service: user-service
config:
claims_to_verify: [exp]
header_names: [Authorization]
- name: request-transformer
service: user-service
config:
add:
headers: ["X-Gateway-Version:1.0"]
remove:
headers: [Cookie]
Kong in Kubernetes
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: rate-limit-api
plugin: rate-limiting
config:
minute: 100
policy: local
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: user-api
annotations:
konghq.com/plugins: rate-limit-api,jwt-auth
spec:
ingressClassName: kong
rules:
- host: api.example.com
http:
paths:
- path: /api/v1/users
pathType: Prefix
backend:
service: { name: user-service, port: { number: 8080 } }
AWS API Gateway
HTTP API (Recommended)
Resources:
HttpApi:
Type: AWS::Serverless::HttpApi
Properties:
StageName: prod
CorsConfiguration:
AllowOrigins: ["[reference URL]"]
AllowMethods: [GET, POST, PUT, DELETE]
AllowHeaders: [Authorization, Content-Type]
Auth:
DefaultAuthorizer: JWTAuthorizer
Authorizers:
JWTAuthorizer:
IdentitySource: $request.header.Authorization
JwtConfiguration:
issuer: [reference URL]
audience: [api.example.com]
DefaultRouteSettings:
ThrottlingBurstLimit: 200
ThrottlingRateLimit: 100
REST API with Usage Plans
UsagePlan:
Type: AWS::ApiGateway::UsagePlan
Properties:
Throttle:
BurstLimit: 200
RateLimit: 100
Quota:
Limit: 100000
Period: MONTH
Rate Limiting
Algorithm Comparison
ALGORITHM HOW IT WORKS TRADE-OFF
---------------------------------------------------------------------------
Fixed Window Count per time window Simple; burst at edges
Sliding Window Weighted current + previous Good accuracy/memory
Token Bucket Tokens refill at steady rate Allows controlled bursts
Leaky Bucket Process at fixed rate, queue Smooth; no bursts
Multi-Tier Strategy
TIER KEY LIMIT PURPOSE
--------------------------------------------------------------
Global - 10,000 req/s Protect infrastructure
Per-IP client IP 100 req/min Prevent abuse
Per-User auth token/key 1,000 req/hr Fair usage
Per-Route path + method 50 req/min Protect heavy endpoints
Rate Limit Response
HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705312800
Authentication Patterns
Gateway Auth Flow
Client -> Gateway -> [Auth Plugin] -> Backend Service
|
Validate token
Extract claims
Inject headers:
X-User-ID, X-User-Role, X-Tenant-ID
|
Strip Authorization header
(backend trusts gateway headers)
API Key Authentication
plugins:
- name: key-auth
service: api-service
config:
key_names: [X-API-Key, apikey]
key_in_header: true
key_in_query: true
hide_credentials: true
Request/Response Transformation
plugins:
- name: response-transformer
config:
add:
headers:
- "Strict-Transport-Security:max-age=31536000; includeSubDomains"
- "X-Content-Type-Options:nosniff"
- "X-Frame-Options:DENY"
remove:
headers: [Server, X-Powered-By]
Routing Patterns
PATH-BASED:
/api/v1/users/* -> user-service:8080
/api/v1/orders/* -> order-service:8080
/api/v2/users/* -> user-service-v2:8080
HEADER-BASED (e.g., mobile vs web):
X-Client-Type: mobile -> user-service-mobile
X-Client-Type: web -> user-service-web
CANARY RELEASES:
10% traffic -> canary backend
90% traffic -> stable backend
Sticky routing per consumer for consistency
Caching
plugins:
- name: proxy-cache
config:
strategy: redis
content_type: [application/json]
request_method: [GET, HEAD]
response_code: [200, 301]
cache_ttl: 300
vary_headers: [Authorization, Accept-Encoding]
cache_control: true
Health Checks
upstreams:
- name: user-service
healthchecks:
active:
http_path: /health
healthy: { interval: 5, successes: 3 }
unhealthy: { interval: 5, http_failures: 3, timeouts: 3 }
passive:
healthy: { successes: 5 }
unhealthy: { http_failures: 5, timeouts: 3 }
targets:
- { target: "user-service-1:8080", weight: 100 }
- { target: "user-service-2:8080", weight: 100 }
Monitoring
METRIC ALERT CONDITION
------------------------------------------------------
Request rate Sudden spike or drop
Error rate (5xx) > 1% sustained
Latency (p99) > 2s
Rate limit hits Sustained high rate
Auth failures Spike (possible attack)
Upstream health Any backend unhealthy
Cache hit ratio < 50%
Production Checklist
ROUTING:
[ ] All routes use HTTPS
[ ] API versioning implemented
[ ] Health check endpoints excluded from auth
SECURITY:
[ ] Auth enforced on all non-public routes
[ ] Rate limiting (global, per-user, per-route)
[ ] Request size limits set
[ ] Security headers on all responses
[ ] CORS with explicit allowed origins
[ ] Sensitive headers stripped before proxying
RELIABILITY:
[ ] Upstream health checks (active + passive)
[ ] Timeouts on all upstream connections
[ ] Circuit breaker for failing backends
[ ] Graceful degradation documented
OBSERVABILITY:
[ ] Access logging (structured JSON)
[ ] Metrics exported (Prometheus/CloudWatch)
[ ] Distributed tracing propagated
[ ] Alerting on error rate, latency, rate limits
When to Use
Use this skill when:
- Designing or implementing api gateway builder solutions
- Reviewing or improving existing api gateway builder approaches
- Making architectural or implementation decisions about api gateway builder
- Learning api gateway builder patterns and best practices
- Troubleshooting api gateway builder-related issues
Do NOT use this skill when:
- The question is about a fundamentally different technology domain
- A more specific sibling skill covers the exact topic needed
- The user needs a complete hands-on tutorial rather than expert guidance
Output Format
# Api Gateway Builder Analysis
## Context Assessment
[Situation summary and constraints]
## Recommended Approach
[Primary recommendation with rationale]
## Implementation Steps
1. [Step with specific details]
2. [Step with specific details]
3. [Step with specific details]
## Trade-offs and Considerations
- [Key trade-off 1]
- [Key trade-off 2]
## Next Steps
- [Immediate action item]
- [Follow-up action item]
Example
Input: "Help me implement api gateway builder for a medium-scale production application"
Output: A structured analysis covering current state assessment, recommended api gateway builder approach with specific patterns, implementation roadmap with milestones, and risk mitigation strategies tailored to the application scale and constraints.
Edge Cases
- Legacy system integration: When api gateway builder must coexist with legacy approaches, provide a gradual migration path rather than a complete rewrite
- Scale mismatch: When the solution complexity exceeds the project scale, recommend a simpler approach and note when to revisit
- Team skill gaps: When the team lacks experience with the recommended approach, include learning resources and simpler alternatives
- Conflicting requirements: When constraints conflict (e.g., performance vs. maintainability), explicitly state the trade-off and recommend based on stated priorities
