Migrating from AWS API Gateway to Zuplo: Feature Mapping, Architecture Translation, and Step-by-Step Guide

AWS API Gateway is a natural fit for teams building on Amazon Web Services, but as API programs grow, its limitations start to show. Velocity Template Language (VTL) for request transformations, region-bound deployments, fragmented tooling across REST and HTTP API types, and CloudFormation-heavy management workflows all add friction that slows teams down. If you’re evaluating a move to a modern, edge-native API gateway, this guide walks you through every step of migrating from AWS API Gateway to Zuplo.

Why Migrate from AWS API Gateway?

AWS API Gateway is capable, but several pain points drive teams to explore alternatives:

Velocity Template Language (VTL) complexity — AWS API Gateway REST APIs use VTL for request and response transformations. VTL is a niche templating language that’s difficult to write, debug, and maintain. There’s no type checking, no IDE support, and errors surface only at runtime. More complex logic requires separate Lambda functions, which adds latency and cost.
Region-bound traffic — AWS API Gateway routes traffic through a single AWS region. Users far from your selected region experience higher latency. To go multi-region, you need to deploy separate API Gateway instances with Route 53, CloudFront, and custom domain mappings — a significant infrastructure lift.
Fragmented API types — AWS offers three distinct API types (REST API, HTTP API, and WebSocket API), each with different feature sets, pricing, and limitations. REST APIs support usage plans and VTL but cost more. HTTP APIs are cheaper but lack features like request validation and API key management. Choosing between them is a permanent decision with trade-offs.
CloudFormation complexity — Managing API Gateway through CloudFormation, SAM, or CDK templates adds significant complexity. Templates are verbose, deployment cycles are slow, and debugging failed deployments through CloudStack events is time-consuming.
Limited rate limiting — AWS API Gateway throttling is global or stage-based. There’s no built-in sliding window rate limiter, no per-user rate limiting granularity, and no way to set dynamic limits based on customer tier without building custom logic in Lambda.
No built-in developer portal — AWS API Gateway does not include a developer-facing portal. The Serverless Developer Portal is a reference implementation that requires self-hosting, maintenance, and manual synchronization with your API definitions.
AWS lock-in — AWS API Gateway is tightly coupled to the AWS ecosystem. Lambda authorizers, Cognito user pools, CloudWatch logging, and IAM roles all assume you’re building exclusively on AWS. Multi-cloud or hybrid architectures require significant workarounds.

Architecture Comparison

Understanding the architectural differences helps you plan a clean migration.

AWS API Gateway’s Architecture

AWS API Gateway uses a regional, service-based model. A typical production setup involves:

An API Gateway instance deployed to a single AWS region (REST API, HTTP API, or WebSocket API)
Stage deployments (dev, staging, production) with stage variables for environment-specific configuration
Lambda integrations for backend logic, with proxy and custom integration modes
VTL mapping templates for request and response transformations (REST API only)
Usage plans and API keys for access control and throttling (REST API only)
Lambda authorizers or Cognito user pools for authentication
CloudFormation, SAM, or CDK for infrastructure-as-code deployment
CloudWatch for logging and monitoring, with separate cost for log storage
Route 53 and CloudFront for custom domains and multi-region routing

Zuplo’s Architecture

Zuplo takes a fundamentally different approach:

Edge-native deployment — Your gateway runs across 300+ data centers worldwide automatically. There’s no single-region deployment to manage or scale.
OpenAPI-native routing — Routes are defined in a standard routes.oas.json file using the OpenAPI specification format, extended with x-zuplo-route for gateway behavior.
TypeScript policies — Instead of VTL templates or Lambda functions, you write policies in TypeScript with full IDE support, type safety, and access to npm packages.
Git-native CI/CD — Every configuration change is version-controlled. Push to GitHub and your gateway deploys to the edge automatically. Every branch gets its own isolated preview environment.
Fully managed — No instances to provision, no CloudFormation templates, no capacity planning. Zuplo handles all infrastructure, scaling, and updates.
Built-in developer portal — Auto-generated from your OpenAPI spec, with API key management and an API explorer included.

Feature Mapping Reference

One of the biggest questions during migration is: “What replaces my AWS API Gateway features?” Below is a mapping of AWS API Gateway’s most common capabilities to their Zuplo equivalents.

Authentication and Authorization

Lambda authorizers → Custom Code Policy — Any custom authentication logic you run in a Lambda authorizer translates to a TypeScript inbound policy. You get the same flexibility with less overhead — no cold starts, no separate function to deploy, no IAM role configuration.
Cognito user pools → AWS Cognito JWT Auth Policy — Zuplo has a dedicated policy for validating Cognito-issued JWT tokens. Configure your AWS region and User Pool ID, and Zuplo validates tokens at the edge.
IAM authorization → JWT Auth Policy or API Key Authentication — IAM-based access is AWS-specific and doesn’t translate directly. Replace it with JWT validation from your identity provider or Zuplo’s managed API key service, depending on your use case.
API keys (REST API) → API Key Authentication — Zuplo’s managed API key service replaces AWS usage plan API keys with globally distributed validation, self-serve key management through the developer portal, and per-consumer metadata.

Traffic Control

Throttling (account-level and stage-level) → Rate Limiting Policy — Supports per-user, per-IP, per-API-key, or custom attribute-based rate limits with a sliding window algorithm. Unlike AWS API Gateway’s token bucket throttling, Zuplo’s rate limiter is globally distributed across all edge locations.
Usage plan quotas → Quota Policy — Enforces hourly, daily, weekly, or monthly usage quotas per consumer. Pair with rate limiting for complete traffic control.
WAF integration — Zuplo runs on Cloudflare’s network, which includes built-in DDoS protection. For application-layer rules, configure Cloudflare WAF or use Zuplo’s IP Restriction Policy for allow/deny lists.
CORS configuration → Built-in CORS Configuration — Configure allowed origins, methods, and headers per route.

Request and Response Transformation

VTL mapping templates → Custom Code Policy — Any VTL transformation logic translates to a TypeScript function with full type checking and IDE support. See the detailed translation examples below.
Header manipulation → Set Headers Policy and Remove Headers Policy — Add, overwrite, or remove request and response headers declaratively.
Query string manipulation → Set Query Params Policy — Add or modify query parameters before forwarding to your backend.
Request body validation → Request Validation Policy — Validates request bodies, query parameters, path parameters, and headers against your OpenAPI schema definitions automatically.

Routing and Integration

Lambda proxy integration → URL Forward Handler — Point Zuplo routes to your Lambda function URLs or Application Load Balancer endpoints. Your Lambda functions stay on AWS.
HTTP proxy integration → URL Rewrite Handler — Rewrite incoming request URLs using template interpolation with access to path parameters, query strings, headers, and environment variables.
Stage variables → Environment variables — Referenced as $env(VARIABLE_NAME) in route configuration or environment.VARIABLE_NAME in TypeScript code (imported from @zuplo/runtime). Secret values are encrypted at rest.
API stages → Git branches with branch-based deployment — Each Git branch gets its own isolated environment with a unique URL. No more managing separate stage deployments.

Monitoring and Analytics

CloudWatch metrics and logs → Zuplo includes built-in request analytics. For deeper observability, integrate with Datadog, Dynatrace, or other providers via log plugins.
X-Ray tracing → Use Zuplo’s logging integrations with OpenTelemetry or Datadog APM for distributed tracing.

Translating AWS Configuration to Zuplo

VTL Mapping Templates → TypeScript Policies

VTL templates are one of the most painful parts of AWS API Gateway to work with. In Zuplo, every transformation is a TypeScript function — readable, testable, and type-safe.

AWS API Gateway (VTL mapping template):

plaintext

#set($inputRoot = $input.path('$'))
{
  "userId": "$inputRoot.user_id",
  "fullName": "$inputRoot.first_name $inputRoot.last_name",
  "email": "$inputRoot.email_address",
  "requestId": "$context.requestId"
}

Zuplo (TypeScript custom code policy):

typescript

import { ZuploContext, ZuploRequest } from "@zuplo/runtime";

export default async function (
  request: ZuploRequest,
  context: ZuploContext,
  options: never,
  policyName: string,
) {
  const body = await request.json();

  const transformed = {
    userId: body.user_id,
    fullName: `${body.first_name} ${body.last_name}`,
    email: body.email_address,
    requestId: context.requestId,
  };

  return new ZuploRequest(request, {
    body: JSON.stringify(transformed),
    headers: {
      "content-type": "application/json",
    },
  });
}

The TypeScript version gives you autocomplete, type checking, and the ability to write unit tests. No more debugging opaque VTL errors in CloudWatch logs.

Lambda Authorizer → Zuplo Custom Code Policy

AWS Lambda authorizers require a separate function deployment, IAM roles, and introduce cold start latency on every auth check. In Zuplo, the same logic runs inline as a TypeScript policy.

AWS Lambda Authorizer (Node.js):

typescript

export const handler = async (event) => {
  const token = event.authorizationToken;

  try {
    const decoded = verifyToken(token);
    return {
      principalId: decoded.sub,
      policyDocument: {
        Version: "2012-10-17",
        Statement: [
          {
            Action: "execute-api:Invoke",
            Effect: "Allow",
            Resource: event.methodArn,
          },
        ],
      },
    };
  } catch (err) {
    throw new Error("Unauthorized");
  }
};

Zuplo (Custom code inbound policy):

typescript

import { ZuploContext, ZuploRequest, HttpProblems } from "@zuplo/runtime";

export default async function (
  request: ZuploRequest,
  context: ZuploContext,
  options: never,
  policyName: string,
) {
  const token = request.headers.get("authorization")?.replace("Bearer ", "");

  if (!token) {
    return HttpProblems.unauthorized(request, context, {
      detail: "Missing authorization token",
    });
  }

  try {
    const decoded = await verifyToken(token);
    request.user = {
      sub: decoded.sub,
      data: decoded,
    };
    return request;
  } catch (err) {
    return HttpProblems.unauthorized(request, context, {
      detail: "Invalid or expired token",
    });
  }
}

No IAM policy documents, no cold starts, no separate deployment pipeline. The policy runs at the edge alongside your gateway.

For standard JWT validation, you don’t even need custom code — Zuplo’s built-in JWT Auth Policy handles it declaratively.

CloudFormation → routes.oas.json

AWS API Gateway configuration in CloudFormation is verbose and error-prone. In Zuplo, routes are defined in a standard OpenAPI file.

AWS CloudFormation (partial):

yaml

Resources:
  ApiGateway:
    Type: AWS::ApiGateway::RestApi
    Properties:
      Name: my-api
  UsersResource:
    Type: AWS::ApiGateway::Resource
    Properties:
      RestApiId: !Ref ApiGateway
      ParentId: !GetAtt ApiGateway.RootResourceId
      PathPart: users
  GetUsersMethod:
    Type: AWS::ApiGateway::Method
    Properties:
      RestApiId: !Ref ApiGateway
      ResourceId: !Ref UsersResource
      HttpMethod: GET
      AuthorizationType: NONE
      Integration:
        Type: HTTP_PROXY
        IntegrationHttpMethod: GET
        Uri: https://api.example.com/users

Zuplo (routes.oas.json):

json

{
  "paths": {
    "/users": {
      "get": {
        "summary": "Get Users",
        "x-zuplo-route": {
          "handler": {
            "export": "urlRewriteHandler",
            "module": "$import(@zuplo/runtime)",
            "options": {
              "rewritePattern": "https://api.example.com/users"
            }
          },
          "policies": {
            "inbound": ["rate-limit", "api-key-auth"]
          }
        }
      }
    }
  }
}

The Zuplo version is a standard OpenAPI document — readable, portable, and compatible with any OpenAPI tooling. Adding policies is a one-line reference instead of nested CloudFormation resources.

Authentication Migration

Authentication is typically the most critical part of any gateway migration. Here’s how to approach each AWS API Gateway authentication mechanism.

Cognito User Pools → Cognito JWT Policy

If you’re using Cognito user pools with AWS API Gateway, migration is straightforward. Zuplo has a dedicated AWS Cognito JWT Auth Policy that validates Cognito-issued tokens directly:

json

{
  "name": "cognito-auth",
  "policyType": "cognito-jwt-auth-inbound",
  "handler": {
    "export": "CognitoJwtInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "region": "us-east-1",
      "userPoolId": "us-east-1_aBcDeFgH"
    }
  }
}

Your Cognito user pool stays on AWS. Zuplo validates the JWT signature, expiration, and claims at the edge. The authenticated user’s claims are available via request.user in your policies and handlers.

Lambda Authorizers → JWT or Custom Code Policy

Most Lambda authorizers exist to validate JWT tokens or check custom credentials. For JWT validation, replace the Lambda authorizer with Zuplo’s built-in JWT Auth Policy or a provider-specific policy. For custom authentication logic, use a Custom Code Policy as shown in the translation examples above.

Available provider-specific JWT policies include: Auth0, AWS Cognito, Clerk, Supabase, Firebase, and Okta.

API Keys (Usage Plans) → Zuplo API Key Management

AWS API Gateway’s API key and usage plan system is limited to REST APIs and requires manual key distribution. Zuplo’s API Key Authentication policy provides a more complete solution:

Add the api-key-inbound policy to your routes
Create consumers with metadata (plan tier, organization, rate limit overrides) through the Zuplo Portal or Developer API
Enable the Developer Portal for self-serve key management

To migrate existing API keys, use Zuplo’s Developer API to programmatically create consumers and import keys so existing client integrations continue working without changes.

Rate Limiting Migration

AWS API Gateway’s throttling is limited to a token bucket algorithm applied globally or per stage. You get a default account-level limit (10,000 requests per second) and can set per-method throttling in usage plans, but there’s no built-in per-user sliding window rate limiter.

Zuplo’s Rate Limiting Policy uses a sliding window algorithm that’s globally distributed across all edge locations:

json

{
  "name": "rate-limit",
  "policyType": "rate-limit-inbound",
  "handler": {
    "export": "RateLimitInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "rateLimitBy": "user",
      "requestsAllowed": 100,
      "timeWindowMinutes": 1
    }
  }
}

Dynamic Rate Limiting by Customer Tier

In AWS, implementing tier-based rate limiting requires custom Lambda logic and usage plan management. In Zuplo, you write a short TypeScript function:

typescript

import {
  CustomRateLimitDetails,
  ZuploContext,
  ZuploRequest,
} from "@zuplo/runtime";

export function rateLimit(
  request: ZuploRequest,
  context: ZuploContext,
  policyName: string,
): CustomRateLimitDetails | undefined {
  const user = request.user;

  if (user.data.customerType === "premium") {
    return {
      key: user.sub,
      requestsAllowed: 1000,
      timeWindowMinutes: 1,
    };
  }

  return {
    key: user.sub,
    requestsAllowed: 50,
    timeWindowMinutes: 1,
  };
}

This runs at the edge — no separate Lambda function, no cold starts, no additional latency.

For longer-term usage caps, Zuplo also offers a Quota Policy that enforces hourly, daily, weekly, or monthly limits per consumer.

Developer Portal Migration

AWS API Gateway does not include a built-in developer portal. The AWS Serverless Developer Portal is a self-hosted reference application that you must deploy, maintain, and manually synchronize with your API definitions. Many teams skip it entirely and build custom documentation separately.

Zuplo’s developer portal is auto-generated from your OpenAPI spec. When you update your routes in routes.oas.json, the portal updates automatically. Features include:

Automatic API documentation — generated directly from your OpenAPI specification, always in sync
API Explorer — developers can test your API directly from the docs
Self-serve API key management — consumers sign up, create keys, and manage them without admin intervention
Custom branding and pages — add custom documentation pages with MDX (Markdown + JSX components)
Built-in analytics — consumers can see their own usage data
Custom domains — host your portal on docs.yourcompany.com

Migration Steps

Export your OpenAPI spec from AWS API Gateway — use the AWS Console (Stages → Export) or the AWS CLI to export your API as OpenAPI 3.0
Import into Zuplo — use the Zuplo Portal or the Zuplo CLI to merge the spec into your routes.oas.json
Add custom pages — migrate any existing documentation to MDX custom pages in the portal
Configure developer sign-in — set up authentication using your identity provider
Update DNS — point your developer portal domain to Zuplo

CI/CD and GitOps

AWS API Gateway’s Workflow

AWS API Gateway relies on infrastructure-as-code tools for deployment:

Write CloudFormation, SAM, or CDK templates
Deploy through AWS CodePipeline, GitHub Actions, or similar CI/CD
Manage stage deployments manually
Stage variables for environment-specific configuration
No automatic preview environments
Rollbacks require redeploying a previous CloudFormation stack

Zuplo’s Workflow

Zuplo uses a Git-native workflow:

All configuration lives in your Git repository
Push to any branch and a preview environment deploys to the edge automatically
Merge to main and production updates in under 20 seconds
Every pull request gets an isolated environment with a unique URL for testing
Rollback by reverting a commit — the previous configuration deploys automatically
Connect directly to GitHub for automatic deployments, or use the Zuplo CLI in any CI/CD pipeline

There are no CloudFormation stacks to manage, no stage deployments to configure, and no deployment pipelines to build. Your Git workflow is your deployment workflow.

Step-by-Step Migration Playbook

A typical AWS API Gateway-to-Zuplo migration follows three phases.

Phase 1: Audit and Setup (Week 1)

Inventory your AWS API Gateway setup:

List every API and its type (REST API, HTTP API, or WebSocket API)
Document all routes, methods, and integration types
Catalog VTL mapping templates and identify which transformations they perform
List all Lambda authorizers and what they validate
Export OpenAPI specs for each API (AWS Console → Stages → Export as OpenAPI 3.0)
Document usage plans, API keys, and throttling configurations
Note stage variables and their values per environment
Identify CloudWatch log groups and alerting rules

Set up Zuplo:

Create a Zuplo account at portal.zuplo.com
Connect your GitHub repository
Import your OpenAPI specs to bootstrap route configuration
Configure backend routing to point at your existing services (Lambda function URLs, ALB endpoints, or direct HTTP endpoints)
Add environment variables for backend URLs and secrets
Set up authentication policies to match your AWS auth configuration
Configure rate limiting and quota policies

Phase 2: Policy Translation and Testing (Week 2)

Translate VTL mapping templates to TypeScript custom code policies using the examples in this guide
Replace Lambda authorizers with Zuplo JWT policies or custom code policies
Map AWS usage plan throttling to Zuplo rate limiting and quota policies
Configure the developer portal
Test all routes against your backend services
Validate authentication flows end-to-end
Run load tests to verify rate limiting behavior
Review logging and observability configuration

Phase 3: Parallel Running and Cutover (Week 3)

Run Zuplo alongside AWS API Gateway to validate behavior:

Deploy your Zuplo project by pushing to your Git repository
Set up a custom domain for your Zuplo gateway
Route a subset of traffic to Zuplo using DNS-based routing
Compare response behavior between AWS API Gateway and Zuplo
Gradually increase traffic to Zuplo as you validate correctness
Complete the full cutover once you’re confident

DNS-based blue-green cutover:

Lower your API domain’s DNS TTL to 60 seconds (24 hours before cutover)
Switch the DNS record to point at Zuplo’s edge network
Monitor error rates and latency
Roll back by reverting DNS if anything goes wrong

Phase 4: Validation and Cleanup (Week 3–4)

After full cutover:

Verify all routes return expected response codes
Confirm authentication works for all methods (Cognito JWT, API keys, custom auth)
Validate rate limiting triggers at correct thresholds
Check that logs flow to your monitoring system
Update developer portal URLs and API documentation
Decommission AWS API Gateway instances and associated resources (Lambda authorizers, usage plans, CloudFormation stacks)

Rollback Strategy

Because Zuplo deployments are Git-based, rollback is straightforward:

Configuration rollback — Revert the Git commit and push. The previous gateway configuration deploys automatically.
DNS rollback — If you kept AWS API Gateway running during the parallel phase, switch DNS back to your AWS endpoints.

Post-Migration Benefits

Once you’ve completed the migration, you’ll immediately benefit from capabilities that AWS API Gateway doesn’t offer.

Global Edge Performance

Your APIs now run at 300+ edge locations worldwide. Requests are automatically routed to the nearest point of presence, reducing latency for users everywhere — not just in the single AWS region where API Gateway was deployed. There’s no multi-region infrastructure to manage, no CloudFront distribution to configure, and no Route 53 routing policies to maintain.

TypeScript Instead of VTL

Custom gateway logic is standard TypeScript — not Velocity Template Language or Lambda functions deployed through CloudFormation. You get full IDE support with autocomplete and type checking, access to the entire npm ecosystem, and the ability to unit test your policies like any TypeScript function. No more debugging opaque VTL errors in CloudWatch.

GitOps-Native Workflow

Every change to your API gateway is a Git commit. Open a pull request and get an isolated preview environment automatically. Review policy changes in code review just like application code. Roll back by reverting a commit. If you’re new to this approach, see our overview of what GitOps is and why it matters. This is a fundamentally better workflow than managing CloudFormation stacks and stage deployments.

Built-in Developer Portal

Instead of deploying and maintaining the AWS Serverless Developer Portal separately, Zuplo generates a full-featured developer portal from your OpenAPI spec. Documentation stays in sync with your API automatically, developers can manage their own API keys, and you can customize the branding and add custom pages — all without a separate application to maintain.

API Monetization

Zuplo can meter and bill API usage out of the box using its monetization capabilities. AWS API Gateway has no native monetization — teams typically build custom billing integrations or use AWS Marketplace, which adds significant complexity.

Faster Deployments

AWS API Gateway deployments through CloudFormation can take minutes. Zuplo deployments complete in under 20 seconds to all 300+ edge locations. That’s a significant improvement for development velocity and incident response.

Frequently Asked Questions

Can I migrate from AWS API Gateway without changing my backend services?

Yes. Zuplo proxies requests to your existing backends — including AWS Lambda, ECS, EKS, EC2, and any publicly reachable service — using the URL Rewrite or URL Forward handler. Your backend services do not need any changes.

How long does an AWS API Gateway migration typically take?

For most teams, a complete migration takes two to three weeks. Teams with straightforward configurations (standard authentication, rate limiting, and proxying) can often complete the migration in under a week. Complex setups with many VTL templates or custom Lambda authorizers may take longer.

What replaces AWS API Gateway usage plans in Zuplo?

Zuplo’s built-in API key authentication policy provides managed API key services with per-consumer metadata, rate limit overrides, and self-serve key management through the developer portal. You can create tiered plans by attaching metadata to API key consumers and using dynamic rate limiting.

Does Zuplo work with AWS Cognito for authentication?

Yes. Zuplo has a dedicated AWS Cognito JWT Auth Policy that validates Cognito-issued tokens at the edge. Configure it with your AWS region and User Pool ID, and Zuplo handles token validation automatically across all 300+ edge locations.

Can I run Zuplo alongside AWS API Gateway during migration?

Yes. The recommended approach is to run both gateways in parallel during the cutover phase, using DNS-based routing to gradually shift traffic from AWS API Gateway to Zuplo.

Do I need to rewrite my Lambda functions to use Zuplo?

No. Zuplo routes requests to any HTTP-reachable backend. Your Lambda functions can remain on AWS — expose them via a function URL or Application Load Balancer, and point Zuplo routes to those endpoints. Over time, you can optionally migrate simple transformation logic into Zuplo’s TypeScript policies to reduce Lambda invocations and latency.

Next Steps

Ready to migrate? Sign up for a free Zuplo account and follow the Getting Started Guide to set up your first gateway in minutes.

For planning your migration:

AWS API Gateway vs Zuplo — a detailed comparison of pricing, performance, and developer experience.
Compare Zuplo and AWS API Gateway — see a feature-by-feature comparison at a glance.
AWS API Gateway Migration Guide (Zuplo Docs) — the technical reference for AWS API Gateway migration in the Zuplo documentation.
Policy Catalog — browse all available built-in policies.
Custom Policies Documentation — learn how to write your own TypeScript policies.
Migrating from Self-Hosted to Managed API Gateway — for general migration strategies and zero-downtime patterns.
AWS API Cost Optimization Strategies — understand hidden AWS API Gateway costs and optimization techniques.