---
title: "Migrating from AWS API Gateway to Zuplo: Feature Mapping, Architecture Translation, and Step-by-Step Guide"
description: "A practical guide to migrating from AWS API Gateway to Zuplo — covering VTL replacement, feature mapping, authentication migration, and a phased plan."
canonicalUrl: "https://zuplo.com/learning-center/migrating-from-aws-api-gateway-to-zuplo"
pageType: "learning-center"
authors: "nate"
tags: "API Gateway, Tutorial"
image: "https://zuplo.com/og?text=Migrating%20from%20AWS%20API%20Gateway%20to%20Zuplo"
---
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.

## What This Guide Covers

1. [Why Migrate from AWS API Gateway?](#why-migrate-from-aws-api-gateway)
2. [Architecture Comparison](#architecture-comparison)
3. [Feature Mapping Reference](#feature-mapping-reference)
4. [Translating AWS Configuration to Zuplo](#translating-aws-configuration-to-zuplo)
5. [Authentication Migration](#authentication-migration)
6. [Rate Limiting Migration](#rate-limiting-migration)
7. [Developer Portal Migration](#developer-portal-migration)
8. [CI/CD and GitOps](#cicd-and-gitops)
9. [Step-by-Step Migration Playbook](#step-by-step-migration-playbook)
10. [Post-Migration Benefits](#post-migration-benefits)
11. [Frequently Asked Questions](#frequently-asked-questions)
12. [Next Steps](#next-steps)

---

## 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](https://zuplo.com/docs/dev-portal/introduction),
  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](https://zuplo.com/docs/policies/custom-code-inbound) —
  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](https://zuplo.com/docs/policies/cognito-jwt-auth-inbound)
  — 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](https://zuplo.com/docs/policies/open-id-jwt-auth-inbound) or
  [API Key Authentication](https://zuplo.com/docs/policies/api-key-inbound) —
  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](https://zuplo.com/docs/policies/api-key-inbound) —
  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](https://zuplo.com/docs/policies/rate-limit-inbound) —
  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](https://zuplo.com/docs/policies/quota-inbound) — 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](https://zuplo.com/docs/policies/ip-restriction-inbound)
  for allow/deny lists.
- **CORS configuration** →
  [Built-in CORS Configuration](https://zuplo.com/docs/programmable-api/custom-cors-policy)
  — Configure allowed origins, methods, and headers per route.

### Request and Response Transformation

- **VTL mapping templates** →
  [Custom Code Policy](https://zuplo.com/docs/policies/custom-code-inbound) —
  Any VTL transformation logic translates to a TypeScript function with full
  type checking and IDE support. See the
  [detailed translation examples](#vtl-mapping-templates--typescript-policies)
  below.
- **Header manipulation** →
  [Set Headers Policy](https://zuplo.com/docs/policies/set-headers-inbound) and
  [Remove Headers Policy](https://zuplo.com/docs/policies/remove-headers-inbound)
  — Add, overwrite, or remove request and response headers declaratively.
- **Query string manipulation** →
  [Set Query Params Policy](https://zuplo.com/docs/policies/set-query-params-inbound)
  — Add or modify query parameters before forwarding to your backend.
- **Request body validation** →
  [Request Validation Policy](https://zuplo.com/docs/policies/request-validation-inbound)
  — Validates request bodies, query parameters, path parameters, and headers
  against your OpenAPI schema definitions automatically.

### Routing and Integration

- **Lambda proxy integration** →
  [URL Forward Handler](https://zuplo.com/docs/handlers/url-forward) — 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](https://zuplo.com/docs/handlers/url-rewrite) — 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](https://zuplo.com/docs/articles/environments) — 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](https://zuplo.com/docs/articles/log-plugins)
  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):**

```velocity
#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](https://zuplo.com/docs/policies/open-id-jwt-auth-inbound)
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](https://zuplo.com/docs/policies/cognito-jwt-auth-inbound)
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](https://zuplo.com/docs/policies/open-id-jwt-auth-inbound) or a
provider-specific policy. For custom authentication logic, use a
[Custom Code Policy](https://zuplo.com/docs/policies/custom-code-inbound) as
shown in the translation examples above.

Available provider-specific JWT policies include:
[Auth0](https://zuplo.com/docs/policies/auth0-jwt-auth-inbound),
[AWS Cognito](https://zuplo.com/docs/policies/cognito-jwt-auth-inbound),
[Clerk](https://zuplo.com/docs/policies/clerk-jwt-auth-inbound),
[Supabase](https://zuplo.com/docs/policies/supabase-jwt-auth-inbound),
[Firebase](https://zuplo.com/docs/policies/firebase-jwt-inbound), and
[Okta](https://zuplo.com/docs/policies/okta-jwt-auth-inbound).

### 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](https://zuplo.com/docs/policies/api-key-inbound)
provides a more complete solution:

1. Add the `api-key-inbound` policy to your routes
2. Create consumers with metadata (plan tier, organization, rate limit
   overrides) through the Zuplo Portal or
   [Developer API](https://zuplo.com/docs/articles/api-key-management)
3. Enable the [Developer Portal](https://zuplo.com/docs/dev-portal/introduction)
   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](https://zuplo.com/docs/policies/rate-limit-inbound) 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](https://zuplo.com/docs/policies/quota-inbound) 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](https://zuplo.com/docs/dev-portal/introduction).
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

1. **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
2. **Import into Zuplo** — use the [Zuplo Portal](https://portal.zuplo.com) or
   the [Zuplo CLI](https://zuplo.com/docs/cli/openapi-merge) to merge the spec
   into your `routes.oas.json`
3. **Add custom pages** — migrate any existing documentation to MDX custom pages
   in the portal
4. **Configure developer sign-in** — set up authentication using your identity
   provider
5. **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](https://zuplo.com/docs/concepts/source-control-and-deployment):

- 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](https://portal.zuplo.com)
- Connect your
  [GitHub repository](https://zuplo.com/docs/articles/source-control)
- 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:

1. Deploy your Zuplo project by pushing to your Git repository
2. [Set up a custom domain](https://zuplo.com/docs/articles/custom-domains) for
   your Zuplo gateway
3. Route a subset of traffic to Zuplo using DNS-based routing
4. Compare response behavior between AWS API Gateway and Zuplo
5. Gradually increase traffic to Zuplo as you validate correctness
6. Complete the full cutover once you're confident

**DNS-based blue-green cutover:**

1. Lower your API domain's DNS TTL to 60 seconds (24 hours before cutover)
2. Switch the DNS record to point at Zuplo's edge network
3. Monitor error rates and latency
4. 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](/learning-center/what-is-gitops). 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](https://zuplo.com/docs/articles/monetization). 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](https://zuplo.com/docs/handlers/url-rewrite) or
[URL Forward](https://zuplo.com/docs/handlers/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](https://zuplo.com/docs/policies/api-key-inbound)
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](https://zuplo.com/docs/policies/rate-limit-inbound).

### Does Zuplo work with AWS Cognito for authentication?

Yes. Zuplo has a dedicated
[AWS Cognito JWT Auth Policy](https://zuplo.com/docs/policies/cognito-jwt-auth-inbound)
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](https://portal.zuplo.com) and follow the
[Getting Started Guide](https://zuplo.com/docs/articles/step-1-setup-basic-gateway)
to set up your first gateway in minutes.

For planning your migration:

- [AWS API Gateway vs Zuplo](/learning-center/zuplo-vs-aws-api-gateway) — a
  detailed comparison of pricing, performance, and developer experience.
- [Compare Zuplo and AWS API Gateway](https://zuplo.com/api-gateways/aws-api-gateway-alternative-zuplo)
  — see a feature-by-feature comparison at a glance.
- [AWS API Gateway Migration Guide (Zuplo Docs)](https://zuplo.com/docs/articles/migrate-from-aws-api-gateway)
  — the technical reference for AWS API Gateway migration in the Zuplo
  documentation.
- [Policy Catalog](https://zuplo.com/docs/policies/overview) — browse all
  available built-in policies.
- [Custom Policies Documentation](https://zuplo.com/docs/policies/custom-code-inbound)
  — learn how to write your own TypeScript policies.
- [Migrating from Self-Hosted to Managed API Gateway](/learning-center/migrate-self-hosted-to-managed-api-gateway)
  — for general migration strategies and zero-downtime patterns.
- [AWS API Cost Optimization Strategies](/learning-center/aws-api-cost-optimization-strategies)
  — understand hidden AWS API Gateway costs and optimization techniques.