Migration Guides

Migrate from AWS API Gateway to Zuplo

Copy page

This guide walks through migrating from AWS API Gateway (REST API, HTTP API, or WebSocket API) to Zuplo. It covers the key differences, concept mapping, and a step-by-step migration process.

Why teams migrate from AWS API Gateway

AWS API Gateway is a natural choice for teams already building on AWS. However, as API programs grow, teams encounter several limitations:

• AWS lock-in — AWS API Gateway only works within the AWS ecosystem. If your backends span multiple cloud providers or you want to avoid single-vendor dependency, you need a multi-cloud solution.
• 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 and maintenance.
• Complex customization — Custom request/response transformations use Velocity Template Language (VTL) for REST APIs, a templating language that is difficult to write, debug, and maintain. More complex logic requires separate Lambda functions.
• Region-bound traffic — AWS API Gateway routes traffic through specific AWS regions, not a global edge network. Users far from your selected region experience higher latency.
• CloudFormation complexity — Managing API Gateway configuration through CloudFormation, SAM, or CDK templates adds significant complexity and slow deployment cycles.
• Limited rate limiting — Throttling is global or stage-based with limited per-user or per-key customization. There is no built-in sliding window rate limiter.

Concept mapping: AWS API Gateway to Zuplo

AWS API Gateway concept	Zuplo equivalent
REST API / HTTP API	OpenAPI route configuration
Resource	Route path in OpenAPI spec
Method	HTTP method on a route
Integration (Lambda, HTTP)	Handler (URL Forward, URL Rewrite, Custom)
Lambda Authorizer	Authentication policy or custom code
API Key + Usage Plan	API Key Authentication + Rate Limiting
Stage	Environment
Stage variables	Environment variables
Request/Response mapping (VTL)	Custom code policy (TypeScript)
CloudFormation / SAM / CDK	GitOps deployment via git push
CloudWatch Logs	Logging integrations (Datadog, Splunk, etc.)
WAF integration	WAF & DDoS protection
Custom domain	Custom domains

Step-by-step migration

Step 1: Export your API definition

AWS API Gateway supports exporting your API as an OpenAPI spec:

Using the AWS Console:

1. Navigate to your API in the API Gateway console.
2. Select Stages and choose the stage to export.
3. Go to the Export tab.
4. Select OpenAPI 3 and JSON format.
5. Choose Export as OpenAPI 3 + API Gateway Extensions to include integration details.

Using the AWS CLI:

Code
aws apigateway get-export \
  --rest-api-id YOUR_API_ID \
  --stage-name prod \
  --export-type oas30 \
  --accepts application/json \
  output.json

Step 2: Clean up and import your OpenAPI spec

The exported spec includes AWS-specific extensions (x-amazon-apigateway-*) that you need to replace with Zuplo configuration.

For each path and method, replace the x-amazon-apigateway-integration with Zuplo's x-zuplo-route extension:

AWS API Gateway export:

Code
{
  "/users": {
    "get": {
      "x-amazon-apigateway-integration": {
        "type": "HTTP_PROXY",
        "httpMethod": "GET",
        "uri": "https://api.backend.example.com/users"
      }
    }
  }
}

Zuplo route configuration:

Code
{
  "/users": {
    "get": {
      "operationId": "get-users",
      "summary": "List users",
      "x-zuplo-route": {
        "corsPolicy": "none",
        "handler": {
          "export": "urlForwardHandler",
          "module": "$import(@zuplo/runtime)",
          "options": {
            "baseUrl": "https://api.backend.example.com"
          }
        },
        "policies": {
          "inbound": []
        }
      }
    }
  }
}

Step 3: Map AWS integrations to Zuplo handlers

AWS integration type	Zuplo handler
HTTP / HTTP_PROXY	URL Forward or URL Rewrite
Lambda	URL Forward to Lambda function URL, or AWS Lambda handler
Mock	Mock API policy

Step 4: Replace VTL mappings with TypeScript

If you use Velocity Template Language (VTL) for request/response transformations, replace them with TypeScript custom code policies.

AWS VTL mapping template:

Code
#set($inputRoot = $input.path('$'))
{
  "userId": "$inputRoot.id",
  "fullName": "$inputRoot.first_name $inputRoot.last_name",
  "email": "$inputRoot.email"
}

Zuplo outbound custom code policy:

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

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

  const transformed = {
    userId: data.id,
    fullName: `${data.first_name} ${data.last_name}`,
    email: data.email,
  };

  return new Response(JSON.stringify(transformed), {
    status: response.status,
    headers: response.headers,
  });
}

Step 5: Migrate Lambda authorizers

If you use Lambda authorizers for authentication, replace them with Zuplo's built-in authentication policies or custom code policies.

For API key authentication:

Replace the Lambda authorizer + usage plan pattern with Zuplo's API Key Authentication policy, which includes built-in key management, a developer portal, and per-key rate limiting.

For JWT / OAuth authentication:

Replace the Lambda authorizer with one of Zuplo's JWT policies:

• Auth0 JWT
• AWS Cognito JWT
• Firebase JWT
• Open ID JWT (generic OIDC)

Step 6: Replace usage plans with Zuplo rate limiting

AWS API Gateway's usage plans provide basic throttling and quota management. Zuplo's rate limiting is more flexible:

AWS usage plan feature	Zuplo equivalent
Throttle rate (requests/sec)	Rate Limiting with timeWindowMinutes
Quota (requests/period)	Quota policy
Per-key throttling	rateLimitBy: "user" on the rate limit policy
Burst limit	Built-in — Zuplo's sliding window handles bursts naturally

Step 7: Deploy and migrate traffic

1. Deploy your Zuplo project by pushing to your connected Git repository.
2. Set up a custom domain for Zuplo.
3. Update your DNS to route traffic through Zuplo.
4. Zuplo can forward requests to your existing AWS backends (Lambda, ALB, ECS) without changes.
5. Monitor traffic and gradually decommission your AWS API Gateway stages.

Keeping AWS backends with Zuplo

You do not need to migrate your backend infrastructure. Zuplo works with any HTTP backend, including:

• AWS Lambda (via function URLs or API Gateway pass-through)
• Application Load Balancers (ALB)
• Amazon ECS / EKS services
• Any AWS service with an HTTP endpoint

Use backend security options like mTLS or shared secrets to secure the connection between Zuplo and your AWS backends.

Next steps

• Set up your first Zuplo gateway
• Add rate limiting
• Add API key authentication
• Configure your developer portal
• Set up source control