Api Gateway

SKILL.md

---
name: api-gateway
description: Smart proxy for external API calls with retry, caching, rate limiting, and fallback providers. Key management with masked display. Zero external dependencies.
---

# API Gateway ⚡

**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