# API Gateway Architecture Specification

## Overview

This document specifies the API Gateway architecture that provides unified edge API access, authentication, authorization, rate limiting, and request routing for all explorer platform services.

## Architecture

```mermaid
flowchart TB
    subgraph Clients
        Web[Web Clients]
        Mobile[Mobile Apps]
        API_Client[API Clients]
    end
    
    subgraph Gateway[API Gateway]
        Router[Request Router]
        Auth[Authentication]
        RateLimit[Rate Limiter]
        Transform[Request Transformer]
        Cache[Response Cache]
        LB[Load Balancer]
    end
    
    subgraph Services[Backend Services]
        Explorer[Explorer API]
        Search[Search Service]
        Analytics[Analytics Service]
        Actions[Action Service]
        Banking[Banking API]
    end
    
    Clients --> Router
    Router --> Auth
    Auth --> RateLimit
    RateLimit --> Transform
    Transform --> Cache
    Cache --> LB
    LB --> Explorer
    LB --> Search
    LB --> Analytics
    LB --> Actions
    LB --> Banking
```

## Gateway Components

### Request Router

**Purpose**: Route requests to appropriate backend services based on path, method, and headers.

**Routing Rules**:
- `/api/v1/blocks/*` → Explorer API
- `/api/v1/transactions/*` → Explorer API
- `/api/v1/addresses/*` → Explorer API
- `/api/v1/search/*` → Search Service
- `/api/v1/analytics/*` → Analytics Service
- `/api/v1/swap/*` → Action Service
- `/api/v1/bridge/*` → Action Service
- `/api/v1/banking/*` → Banking API
- `/graphql` → Explorer API (GraphQL endpoint)

**Implementation**: NGINX, Kong, AWS API Gateway, or custom router

### Authentication

**Purpose**: Authenticate requests and extract user/API key information.

**Methods**:
1. **API Key Authentication**:
   - Header: `X-API-Key: <key>`
   - Query parameter: `?api_key=<key>` (less secure)
   - Validate key hash against database
   - Extract user_id and tier from key

2. **OAuth 2.0**:
   - Bearer token: `Authorization: Bearer <token>`
   - Validate JWT token
   - Extract user claims

3. **Session Authentication**:
   - Cookie-based for web clients
   - Validate session token

**Anonymous Access**: Allow unauthenticated requests with lower rate limits

### Authorization

**Purpose**: Authorize requests based on user permissions and API key tier.

**Authorization Checks**:
- API key tier (free, pro, enterprise)
- User roles and permissions
- Resource-level permissions (user's own data)
- IP whitelist restrictions

**Enforcement**:
- Block unauthorized requests (403 Forbidden)
- Filter responses based on permissions
- Log authorization failures

### Rate Limiting

**Purpose**: Prevent abuse and ensure fair usage.

**Rate Limiting Strategy**:

**Tiers**:
1. **Anonymous**: 10 req/s, 100 req/min
2. **Free API Key**: 100 req/s, 1000 req/min
3. **Pro API Key**: 500 req/s, 5000 req/min
4. **Enterprise API Key**: 1000 req/s, unlimited

**Per-Endpoint Limits**:
- Simple queries (GET): Higher limits
- Complex queries (search, analytics): Lower limits
- Write operations (POST): Strict limits

**Implementation**:
- Token bucket algorithm
- Redis for distributed rate limiting
- Sliding window for smooth rate limiting

**Rate Limit Headers**:
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200
```

**Response on Limit Exceeded**:
```json
{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Please try again later.",
  "retry_after": 60
}
```
HTTP Status: 429 Too Many Requests

### Request Transformation

**Purpose**: Transform requests before forwarding to backend services.

**Transformations**:
- Add user context headers (user_id, tier)
- Normalize request format
- Add tracing headers (request_id, trace_id)
- Validate and sanitize input
- Add default parameters

**Example Headers Added**:
```
X-User-ID: <uuid>
X-API-Tier: pro
X-Request-ID: <uuid>
X-Trace-ID: <uuid>
```

### Response Caching

**Purpose**: Cache responses to reduce backend load and improve latency.

**Cacheable Endpoints**:
- Block data (cache for 10 seconds)
- Token metadata (cache for 1 hour)
- Contract ABIs (cache for 1 hour)
- Analytics aggregates (cache for 5 minutes)

**Cache Keys**:
- Include path, query parameters, API key tier
- Exclude user-specific parameters

**Cache Headers**:
- `Cache-Control: public, max-age=60`
- `ETag` for conditional requests
- `Vary: X-API-Key` to vary by tier

**Cache Invalidation**:
- Time-based expiration
- Manual invalidation on data updates
- Event-driven invalidation

### Load Balancing

**Purpose**: Distribute requests across backend service instances.

**Strategies**:
- Round-robin: Even distribution
- Least connections: Send to least loaded instance
- Health-aware: Skip unhealthy instances

**Health Checks**:
- HTTP health check endpoint: `/health`
- Check interval: 10 seconds
- Unhealthy threshold: 3 consecutive failures
- Recovery threshold: 2 successful checks

## Request/Response Flow

### Request Flow

1. **Client Request** → Gateway
2. **Routing** → Determine target service
3. **Authentication** → Validate credentials
4. **Authorization** → Check permissions
5. **Rate Limiting** → Check limits
6. **Cache Check** → Return cached if available
7. **Request Transformation** → Add headers, normalize
8. **Load Balancing** → Select backend instance
9. **Forward Request** → Send to backend service
10. **Response Handling** → Transform, cache, return

### Response Flow

1. **Backend Response** → Gateway
2. **Response Transformation** → Add headers, format
3. **Cache Storage** → Store if cacheable
4. **Error Handling** → Format errors consistently
5. **Response to Client** → Return response

## Error Handling

### Error Format

**Standard Error Response**:
```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please try again later.",
    "details": {},
    "request_id": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}
```

### Error Codes

- `400 Bad Request`: Invalid request
- `401 Unauthorized`: Authentication required
- `403 Forbidden`: Authorization failed
- `404 Not Found`: Resource not found
- `429 Too Many Requests`: Rate limit exceeded
- `500 Internal Server Error`: Server error
- `502 Bad Gateway`: Backend service unavailable
- `503 Service Unavailable`: Service temporarily unavailable
- `504 Gateway Timeout`: Backend timeout

## Security Considerations

### Request Validation

- Validate request size (max 10MB)
- Validate content-type
- Sanitize input to prevent injection
- Validate API key format

### DDoS Protection

- Rate limiting per IP
- Connection limits
- Request size limits
- WAF integration (Cloudflare)

### TLS/SSL

- Require HTTPS for all requests
- TLS 1.2+ only
- Strong cipher suites
- Certificate management

## Monitoring and Observability

### Metrics

**Key Metrics**:
- Request rate (requests/second)
- Response time (p50, p95, p99)
- Error rate (by error type)
- Cache hit rate
- Rate limit hits
- Backend service health

### Logging

**Log Fields**:
- Request ID
- User ID / API Key
- Method, path, query parameters
- Response status, latency
- Backend service called
- Error messages

**Log Level**: INFO for normal requests, ERROR for failures

### Tracing

- Add trace ID to requests
- Propagate trace ID to backend services
- Correlate requests across services

## Configuration

### Gateway Configuration

```yaml
gateway:
  port: 443
  health_check_path: /health
  
  rate_limiting:
    redis_url: "redis://..."
    default_limit: 100
    default_period: 60
  
  cache:
    redis_url: "redis://..."
    default_ttl: 60
  
  services:
    explorer_api:
      base_url: "http://explorer-api:8080"
      health_check: "/health"
    
    search_service:
      base_url: "http://search-service:8080"
      health_check: "/health"
```

## Implementation Options

### Option 1: NGINX + Lua

- High performance
- Custom logic with Lua
- Good caching support

### Option 2: Kong

- API Gateway features out of the box
- Plugin ecosystem
- Good rate limiting

### Option 3: AWS API Gateway

- Managed service
- Good integration with AWS services
- Cost considerations

### Option 4: Custom Gateway (Go/Node.js)

- Full control
- Custom features
- More maintenance

**Recommendation**: Start with Kong or NGINX, migrate to custom if needed.

## References

- REST API: See `rest-api.md`
- Authentication: See `../security/auth-spec.md`
- Rate Limiting: See `../security/ddos-protection.md`