Api Gateway

Smart proxy for external API calls with retry, caching, rate limiting, and fallback providers. Key management with masked display. Zero external dependencies.

Stop duplicating API logic. Start routing through one smart gateway.

The Problem

Every agent call to an external API needs its own retry logic, caching, rate limit handling, and key management. That's the same code repeated across every skill.

API Gateway centralizes all of that into one tool.

Quick Start

Make an API call with retry and caching

bash

node skills/api-gateway/api-gateway.js --call openai https://api.openai.com/v1/chat/completions '{"model":"gpt-4","messages":[{"role":"user","content":"hello"}]}'

Automatically retries up to 3 times with exponential backoff, caches responses for 5 minutes.

Dry run (preview without executing)

bash

node skills/api-gateway/api-gateway.js --call --dry-run openai https://api.openai.com/v1/chat/completions

Manage API keys

bash

# List configured keys (masked)
node skills/api-gateway/api-gateway.js --keys

# Add a key
node skills/api-gateway/api-gateway.js --keys add openai sk-abc123

# Remove a key
node skills/api-gateway/api-gateway.js --keys remove openai

Check cache status

bash

# Show cache entries
node skills/api-gateway/api-gateway.js --cache

# Clear cache
node skills/api-gateway/api-gateway.js --cache --clear

Check rate limit status

bash

node skills/api-gateway/api-gateway.js --rate openai

Set fallback provider

bash

node skills/api-gateway/api-gateway.js --fallback openai anthropic

If the primary provider fails or is rate-limited, automatically tries the fallback.

Status overview

bash

node skills/api-gateway/api-gateway.js --status

Circuit breaker status

bash

node skills/api-gateway/api-gateway.js --circuit --status

Reset a circuit

bash

node skills/api-gateway/api-gateway.js --circuit <provider> --reset

Features

Retry with Exponential Backoff

• 3 retry attempts by default
• Exponential backoff (1s, 2s, 4s)
• All failures logged with attempt count

Response Caching

• 5-minute TTL on cached responses
• Cache key = provider + endpoint + body
• Auto-evicts expired entries
• Cache hit detection prevents redundant calls

Rate Limit Handling

• Tracks remaining requests from x-ratelimit-remaining headers
• Auto-fallback when rate limited (if configured)
• Status check via --rate

Key Management

• Masked display (first 4 + last 4 chars)
• Per-provider key storage in memory/api-gateway/keys.json
• Add/remove keys without exposing full values

Fallback Providers

• Configurable per-provider fallback chain
• Automatic failover on rate limit or error
• No manual intervention needed

Circuit Breaker

• Tracks failure rates per provider
• Opens circuit after 5 consecutive failures
• Auto-recovers after 30s cooldown (HALF-OPEN state)
• Prevents cascading failures and saves API costs
• CLI visibility: --circuit --status + --circuit <name> --reset

Configuration

Data files stored in: memory/api-gateway/

• keys.json — API key storage
• fallbacks.json — Fallback provider mappings
• cache.json — Response cache
• rate-limits.json — Rate limit tracking
• request-log.json — Request history (last 1000)
• circuit-state.json — Circuit breaker state per provider

Override data directory:

bash

--dir /path/to/data

Agent Protocol

When making API calls:

1. Use the gateway — --call <provider> <endpoint> [body] instead of direct fetch
2. Add keys first — --keys add before first use
3. Set fallbacks — --fallback primary secondary for critical providers
4. Check cache — --cache during heartbeats to monitor usage
5. Dry run — --call --dry-run before executing important calls

Security Notes

• Keys stored as plain text in JSON (same risk as .env files)
• For production, integrate with a secrets manager
• Masked output prevents accidental exposure in logs
• Request log limited to 1000 entries

Comparison

Approach	Retry	Cache	Rate Limit	Fallback
Manual fetch	❌	❌	❌	❌
Custom wrapper	⚠️	⚠️	⚠️	❌
API Gateway	✅	✅	✅	✅

API Gateway gives you retry + caching + rate limiting + fallback in one call.

Design Principles

1. Zero setup — Works immediately, no config needed
2. No dependencies — Pure Node.js http/https, no npm packages
3. Resilient — Retry, fallback, and rate limit handling built in
4. Transparent — Masked keys, cache status, request logging
5. Composable — Works with any HTTP API, not just specific providers