Getting Started with Toran

Learn how to set up and deploy your first API gateway in minutes.

Prerequisites

• Node.js 18+ and npm 9+
• MongoDB Atlas account (free tier works)
• Cloudflare account

Step 1: Set Up MongoDB

Create a MongoDB Atlas cluster and enable the Data API. Follow the instructions in docs/mongodb-setup.md to create the required collections and indexes.

# Create collections
db.createCollection("gateways");
db.createCollection("routes");
db.createCollection("logs");

# Create indexes
db.gateways.createIndex({ subdomain: 1 }, { unique: true });
db.routes.createIndex({ gatewayId: 1, priority: -1 });
db.logs.createIndex({ expiresAt: 1 }, { expireAfterSeconds: 0 });

Step 2: Configure Environment Variables

Set up your Cloudflare Worker secrets:

# Using Wrangler CLI
wrangler secret put MONGODB_API_URL
# Paste: https://data.mongodb-api.com/app/<APP-ID>/endpoint/data/v1

wrangler secret put MONGODB_API_KEY
# Paste: your-api-key-here

wrangler secret put MONGODB_DATABASE
# Paste: toran

Step 3: Create Your First Gateway

Insert a test gateway into MongoDB:

db.gateways.insertOne({
  subdomain: "api",
  name: "Production API",
  description: "Main API gateway",
  baseUrl: "https://api.example.com",
  active: true,
  variables: {
    API_KEY: {
      value: "your-api-key",
      secret: true,
      description: "API authentication key"
    },
    BASE_URL: {
      value: "https://api.example.com",
      secret: false,
      description: "API base URL"
    }
  },
  defaults: {
    timeout: 30000,
    followRedirects: true,
    cacheEnabled: false,
    logLevel: "full"
  },
  createdAt: new Date(),
  updatedAt: new Date(),
  stats: {
    totalRequests: 0,
    totalRoutes: 0,
    lastRequestAt: null
  }
});

Step 4: Create a Route

Add a route to your gateway:

db.routes.insertOne({
  gatewayId: ObjectId("your-gateway-id"),
  path: "/users/:id",
  method: ["GET"],
  priority: 100,
  active: true,

  destination: {
    type: "proxy",
    url: "${BASE_URL}/v1/users/${params.id}",
    preservePath: false
  },

  parameters: {
    id: {
      type: "uuid",
      required: true,
      description: "User ID"
    }
  },

  preMutations: {
    headers: [{
      type: "add",
      key: "X-API-Key",
      value: "${variables.API_KEY}"
    }]
  },

  postMutations: {
    headers: [{
      type: "add",
      key: "X-Gateway",
      value: "Toran"
    }]
  },

  cache: {
    enabled: true,
    ttl: 300,
    varyBy: {
      path: true,
      method: true,
      queryParams: [],
      headers: [],
      body: false
    },
    conditions: {
      statusCodes: [200]
    }
  },

  name: "Get User by ID",
  description: "Fetch user details",
  tags: ["users"],
  createdAt: new Date(),
  updatedAt: new Date(),
  stats: {
    totalRequests: 0,
    cacheHits: 0,
    cacheMisses: 0,
    avgDuration: 0,
    lastRequestAt: null
  }
});

Step 5: Deploy the Worker

# Deploy to Cloudflare Workers
npm run deploy:worker

# Your gateway will be available at:
# https://api.toran.dev/users/123

Step 6: Test Your Gateway

Make a request to your gateway:

curl https://api.toran.dev/users/123

# Response headers will include:
# X-Toran-Gateway: api
# X-Toran-Route: Get User by ID
# X-Toran-Cache: MISS (first request)
# X-Gateway: Toran (from post-mutation)

Next Steps

• Deploy Admin UI: Manage gateways and routes visually
• Add More Routes: Configure different paths and methods
• Set Up Mutations: Transform requests and responses
• Monitor Logs: Track requests and performance