Migration Guides

Migrate from Google Apigee to Zuplo

Copy page

This guide walks through migrating from Google Apigee (including Apigee X, Apigee hybrid, and legacy Apigee Edge) to Zuplo. It covers the key differences, concept mapping, policy translation, and a step-by-step migration process.

Why teams migrate from Apigee

Apigee is one of the oldest API management platforms, acquired by Google in 2016. While it offers deep enterprise analytics and compliance features, teams increasingly find the platform difficult to justify:

• Apigee Edge end-of-life — Google has been sunsetting legacy Apigee Edge (on-premises and private cloud) versions, pushing customers to migrate to Apigee X on Google Cloud. This forced migration is an opportunity to evaluate modern alternatives.
• Google Cloud lock-in — Apigee X is tightly coupled to Google Cloud Platform. While Apigee hybrid exists, it adds operational complexity. Teams running multi-cloud or non-GCP backends face unnecessary friction.
• High cost — Apigee pricing starts at approximately $1,500/month for just 100K requests, with separate charges for environments, analytics, and developer portals. Enterprise contracts often require five-figure monthly commitments.
• XML-based policy configuration — Apigee policies are configured in verbose XML files that are difficult to read, maintain, and version control. Custom logic uses a limited JavaScript engine.
• Slow deployment cycles — Apigee deployments can take several minutes to propagate, slowing down the development iteration loop.
• Drupal-based developer portal — Apigee's developer portal is built on Drupal, requiring significant setup, customization, and ongoing maintenance.

Concept mapping: Apigee to Zuplo

Apigee concept	Zuplo equivalent
API Proxy	Routes in your OpenAPI spec
ProxyEndpoint	Route path + handler
TargetEndpoint	URL forward handler base URL
Policy (XML)	Policy (TypeScript) or built-in policy
PreFlow / PostFlow	Inbound / outbound policies
Conditional flow	Custom code in a custom policy
SharedFlow	Reusable custom code module
Environment	Environment
API Product	API key with metadata
Developer App	API key consumer
Apigee Developer Portal	Zuplo Developer Portal
VerifyAPIKey policy	API Key Authentication
OAuthV2 policy	JWT authentication policies
SpikeArrest	Rate Limiting
Quota	Quota policy
KVM (Key Value Map)	Environment variables
Management API	Zuplo API

Step-by-step migration

Step 1: Export your API definitions

Apigee API proxies contain OpenAPI specs or can generate them. Export your API definitions:

1. In the Apigee console, navigate to your API proxy.
2. Download the OpenAPI spec from the Develop tab, or export the proxy bundle as a ZIP file and extract the spec.
3. If no spec exists, create one from your proxy's endpoint and resource definitions.

Step 2: Map Apigee policies to Zuplo policies

The following table maps common Apigee policies to Zuplo equivalents:

Apigee policy	Zuplo policy
VerifyAPIKey	API Key Authentication
OAuthV2	Open ID JWT Authentication
BasicAuthentication	Basic Authentication
SpikeArrest	Rate Limiting
Quota	Quota
AssignMessage	Set Headers or Set Body
ExtractVariables	Custom Code Policy
XMLToJSON / JSONToXML	XML to JSON or custom code
RaiseFault	Custom code returning an error Response
AccessControl	IP Restriction
CORS	Built-in CORS configuration
JavaScript callout	Custom Code Policy (TypeScript)
ServiceCallout	Custom Code Policy using fetch()

Step 3: Translate policy configuration

Here is an example of translating an Apigee SpikeArrest policy to a Zuplo rate limit policy.

Apigee XML policy:

Code
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SpikeArrest name="SA-RateLimit">
  <Rate>100pm</Rate>
  <Identifier ref="request.header.x-api-key"/>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

Zuplo policy configuration:

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

Step 4: Translate JavaScript callouts to TypeScript

If you use Apigee JavaScript callouts, rewrite them as Zuplo custom code policies in TypeScript.

Apigee JavaScript callout:

Code
var apiKey = context.getVariable("request.header.x-api-key");
var clientId = context.getVariable("request.header.x-client-id");

if (!apiKey || !clientId) {
  context.setVariable("isError", true);
  context.setVariable("errorMessage", "Missing required headers");
}

var payload = JSON.parse(context.getVariable("request.content"));
payload.enriched = true;
payload.timestamp = new Date().toISOString();
context.setVariable("request.content", JSON.stringify(payload));

Equivalent Zuplo TypeScript policy:

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

export default async function (
  request: ZuploRequest,
  context: ZuploContext,
  options: never,
  policyName: string,
) {
  const apiKey = request.headers.get("x-api-key");
  const clientId = request.headers.get("x-client-id");

  if (!apiKey || !clientId) {
    return HttpProblems.badRequest(request, context, {
      detail: "Missing required headers",
    });
  }

  const payload = await request.json();
  payload.enriched = true;
  payload.timestamp = new Date().toISOString();

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

Step 5: Migrate your developer portal

Apigee's Drupal-based developer portal requires significant setup and maintenance. Zuplo's Developer Portal is automatically generated from your OpenAPI spec and includes:

• Interactive API reference documentation
• Self-serve API key management
• Built-in authentication
• Customizable theming
• Zero maintenance — it updates automatically when your API changes

Step 6: Migrate environment configuration

Apigee KVMs to Zuplo environment variables:

Apigee uses Key Value Maps (KVMs) for environment-specific configuration. In Zuplo, use environment variables:

Apigee KVM	Zuplo environment variable
kvm.get("backend-url")	$env(BACKEND_URL) in route config
context.getVariable("my-kvm.key")	context.env.MY_KEY in custom code
Encrypted KVM entries	Secret environment variables

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 your Zuplo gateway.
3. Route a subset of traffic to Zuplo using DNS-based traffic splitting.
4. Monitor both gateways and compare behavior.
5. Gradually shift all traffic to Zuplo.
6. Decommission your Apigee environment.

Apigee Edge to Zuplo: a special case

If you are migrating from legacy Apigee Edge (on-premises or private cloud) rather than Apigee X, the migration to Zuplo is an opportunity to modernize without the complexity of moving to Apigee X:

• Skip the Apigee X migration — Instead of migrating from Edge to X (which Google recommends but requires significant effort), migrate directly to Zuplo.
• Eliminate infrastructure — Apigee Edge requires managing on-premises infrastructure. Zuplo is fully managed.
• Reduce costs — Apigee X pricing is often higher than Edge licensing. Zuplo offers transparent, usage-based pricing starting with a free tier.

Next steps

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