Gateway as Code

Define your API gateway routes in version-controllable configuration files.

Overview

Gateway as Code (GaC) allows you to define your API gateway routes in a configuration file (nolxy.config.ts or .json) and sync them to the database.

Version Control

Routes are reviewable, versioned, and promotable across environments

CI/CD Integration

Sync routes as part of your deployment pipeline

No Runtime Penalty

Workers use compiled in-memory patterns; no per-request file I/O

Developer-First DX

Familiar config-as-code workflow with TypeScript support

Quick Start

1. Create a Config File

nolxy.config.json

{
  "version": "1.0.0",
  "name": "my-api-gateway",
  "routes": [
    {
      "name": "users-api",
      "path": "/users",
      "targetUrl": "http://localhost:8000",
      "method": "GET",
      "description": "Get all users"
    },
    {
      "name": "user-by-id",
      "path": "/users/:id",
      "targetUrl": "http://localhost:8000",
      "description": "Get user by ID"
    }
  ]
}

2. Preview Changes (Dry Run)

bash

nolxy sync --config ./nolxy.config.json --user-id 1 --dry-run

3. Apply Changes

bash

nolxy sync --config ./nolxy.config.json --user-id 1

Configuration Schema

Root Object

Field	Type	Required	Description
`version`	string	No	Semver version (default: "1.0.0")
`name`	string	No	Config name (default: "nolxy-config")
`routes`	RouteConfig[]	Yes	Array of route configurations

RouteConfig

Field	Type	Required	Description
`name`	string	Yes	Unique identifier (stable key)
`path`	string	Yes	Route path (e.g., /users/:id, /api/*)
`targetUrl`	string	Yes	Upstream URL
`method`	string	No	HTTP method: GET, POST, PUT, DELETE, PATCH, etc. (null = all methods)
`description`	string	No	Route description
`timeout`	number	No	Request timeout in ms (default: 30000)
`isActive`	boolean	No	Enable/disable route (default: true)
`headers`	Record<string, string>	No	Custom headers to forward to upstream (key-value pairs)
`backendSecret`	string	No	Secret token sent to backend for verification
`responseSchema`	object	No	JSON Schema for response validation
`cache`	CacheConfig	No	Response caching configuration
`retry`	RetryConfig	No	Retry configuration
`cors`	CorsConfig	No	CORS configuration
`circuitBreaker`	CircuitBreakerConfig	No	Circuit breaker configuration
`pipeline`	PipelineConfig	No	Request/response transformation pipeline

CacheConfig

Field	Type	Required	Description
`enabled`	boolean	Yes	Enable response caching
`ttl`	number	No	Cache TTL in seconds (default: 60)
`keyHeaders`	string[]	No	Headers to include in cache key (e.g., ["Authorization"])
`statusCodes`	number[]	No	HTTP status codes to cache (default: [200])

RetryConfig

Field	Type	Required	Description
`enabled`	boolean	Yes	Enable automatic retries
`count`	number	No	Max retry attempts (default: 3)
`delay`	number	No	Delay between retries in ms (default: 100)
`on`	number[]	No	HTTP status codes to retry on (e.g., [502, 503, 504])

CorsConfig

Field	Type	Required	Description
`enabled`	boolean	Yes	Enable CORS handling
`allowOrigins`	string[]	No	Allowed origins (e.g., ["https://example.com"])
`allowMethods`	string[]	No	Allowed HTTP methods (e.g., ["GET", "POST"])
`allowHeaders`	string[]	No	Allowed request headers
`exposeHeaders`	string[]	No	Headers exposed to the browser
`maxAge`	number	No	Preflight cache duration in seconds (default: 86400)
`credentials`	boolean	No	Allow credentials (cookies, auth headers)

CircuitBreakerConfig

Field	Type	Required	Description
`enabled`	boolean	Yes	Enable circuit breaker
`failureThreshold`	number	No	Failures before opening circuit (default: 5)
`failureWindow`	number	No	Window to count failures in ms (default: 60000)
`successThreshold`	number	No	Successes needed to close circuit (default: 3)
`timeout`	number	No	Time before half-open attempt in ms (default: 30000)

PipelineConfig

Field	Type	Required	Description
`request`	Transform[]	No	Request transformations applied before forwarding
`response`	Transform[]	No	Response transformations applied before returning

Each Transform has type (string) and optional config (object) fields.

Stable Route Identity

Routes are identified by their name field, not by path + method. This means:

✓ Changing path/method preserves route ID

Analytics and logs stay associated

Cache keys remain stable

✗ Duplicate names are rejected

Each name must be unique

Path+method combos also checked

CI/CD Integration

Use Service Accounts for CI/CD pipelines. Create one from Dashboard → Service Accounts with the gateway:sync and gateway:validate permissions, then store the key in your CI secrets.

GitHub Actions Example

.github/workflows/deploy-gateway.yml

name: Deploy Gateway Config

on:
  push:
    branches: [main]
    paths:
      - 'nolxy.config.json'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '24'
      
      - name: Install Nolxy CLI
        run: npm install -g @nolxy/cli
      
      - name: Validate config
        run: nolxy validate --config ./nolxy.config.json
        env:
          NOLXY_SERVICE_KEY: ${{ secrets.NOLXY_SERVICE_KEY }}
      
      - name: Sync config (dry-run on PR)
        if: github.event_name == 'pull_request'
        run: nolxy sync --config ./nolxy.config.json --dry-run
        env:
          NOLXY_SERVICE_KEY: ${{ secrets.NOLXY_SERVICE_KEY }}
      
      - name: Sync config (apply on main)
        if: github.ref == 'refs/heads/main'
        run: nolxy sync --config ./nolxy.config.json
        env:
          NOLXY_SERVICE_KEY: ${{ secrets.NOLXY_SERVICE_KEY }}

Dashboard UI

You can also manage Gateway as Code configurations from the dashboard:

Read-only mode: If a route is managed by code, the UI shows a "Managed by Code" badge and disables editing.
Drift Detection: The UI warns if the actual config differs from the last synced version.

Dashboard UI

Visual editor with preview, validation, and sync capabilities

Cache Invalidation

When routes are updated via sync, all caches are invalidated automatically. Route changes take effect immediately across all workers — no restart required. Response caches for affected routes are also cleared.

Best Practices

Use Environment Variables

Different targetUrl per environment (dev/staging/prod)

Dry Run First

Always preview changes with --dry-run before applying

Version Control

Commit config files to git for full history and rollback capability

Stable Names

Never change route name unless you want to recreate the route

Analytics Dashboard Request Validation