Route Schema

Complete reference for route configuration.

Route Object

interface RouteConfig {
  path: string;
  method: 'get' | 'post' | 'put' | 'patch' | 'delete';
  description?: string;
  tags?: string[];
  requireAuth?: boolean;
  authProvider?: 'jwt' | 'firebase';
  requiredPermissions?: string[];
  supabaseQueries?: Query[];
  integrations?: Integration[];
  request?: RequestSchema;
  response?: ResponseSchema;
  cache?: RouteCache;
  rateLimit?: RateLimitOptions;
}

Properties

path

Endpoint path with optional parameters.

"/users"
"/users/:id"
"/users/:userId/posts/:postId"

method

HTTP method (lowercase).

"get" | "post" | "put" | "patch" | "delete"

description

OpenAPI description for documentation.

"Get user by ID"

tags

OpenAPI tags for grouping.

["Users", "Admin"]

requireAuth

Require JWT authentication.

true | false

authProvider

Authentication provider.

"jwt" | "firebase"

requiredPermissions

RBAC permissions required.

["users:read", "users:write"]

supabaseQueries

Database operations. See Query Schema.

integrations

External service calls.

interface Integration {
  type: string;
  action: string;
  params?: Record<string, any>;
}

request

Request validation schema.

interface RequestSchema {
  body?: SchemaObject;
  params?: SchemaObject;
  query?: SchemaObject;
}

interface SchemaObject {
  [field: string]: {
    type: 'string' | 'number' | 'boolean' | 'array' | 'object';
    required?: boolean;
    format?: string;
    minimum?: number;
    maximum?: number;
    minLength?: number;
    maxLength?: number;
    pattern?: string;
    enum?: any[];
    items?: SchemaObject;
  };
}

response

Response schema for documentation.

interface ResponseSchema {
  type: 'object' | 'array';
  properties?: Record<string, any>;
  items?: Record<string, any>;
}

cache

Route-specific caching.

interface RouteCache {
  enabled: boolean;
  ttl?: number;  // Seconds
}

rateLimit

Route-specific rate limiting.

interface RateLimitOptions {
  windowMs?: number;
  max: number;
  message?: string;
  statusCode?: number;
}

Examples

Basic GET

{
  "path": "/users",
  "method": "get",
  "description": "List all users",
  "tags": ["Users"],
  "supabaseQueries": [{
    "table": "users",
    "operation": "select"
  }]
}

Protected POST

{
  "path": "/users",
  "method": "post",
  "description": "Create user",
  "tags": ["Users"],
  "requireAuth": true,
  "requiredPermissions": ["users:create"],
  "request": {
    "body": {
      "name": { "type": "string", "required": true },
      "email": { "type": "string", "format": "email", "required": true }
    }
  },
  "supabaseQueries": [{
    "table": "users",
    "operation": "insert",
    "data": {
      "name": "{{body.name}}",
      "email": "{{body.email}}"
    }
  }]
}

With Integration

{
  "path": "/notify",
  "method": "post",
  "requireAuth": true,
  "integrations": [{
    "type": "slack",
    "action": "sendMessage",
    "params": {
      "channel": "#general",
      "text": "{{body.message}}"
    }
  }]
}