01
The choice you make first
The Editions
Apigee comes in three forms with confusingly similar names. They share most concepts but differ in how the runtime is deployed, what it costs, and whether they're still being invested in.
Apigee X Modern
X
GCP-managed, the default for new deployments
- Runtime location GCP
- Control plane Apigee SaaS
- Multi-region Native
- GraphQL/gRPC Yes
- OTel tracing Yes
- Pricing model Pay-go or subscription
- Investment level Active
Hybrid Self-host
Hybrid
Runtime on your K8s, plane on GCP
- Runtime location Your K8s
- Control plane Apigee SaaS
- Cloud-agnostic AKS · EKS · GKE · On-prem
- Required for data residency
- OTel tracing Yes
- Pricing model Pay-go or subscription
- Investment level Active
Edge Sunset
Edge
The legacy SaaS — migrate off
- Runtime location Apigee SaaS
- Control plane Same
- End-of-life Past dates
- Migration target X or Hybrid
- Net New deployments Discouraged
- Pricing model Legacy contracts
- Investment level Maintenance
▸ Decision heuristic
New deployment? Apigee X. Need on-prem or data residency? Apigee Hybrid. Already on Edge? Plan the migration now.
Edge customers should treat migration as a 12–24 month project. The policy library is largely compatible, but environments, KVMs, and shared flows need to be re-deployed. Edge proxy bundles export cleanly; the rebuild is in CI/CD, dev portal, and analytics integrations.
02
The 18 you actually use
Policy Library
Apigee has ~85 built-in policies — including a recent AI/LLM policy family. Most teams use the same dozen. Here are the ones worth knowing by name.
| Policy | Category | What it does |
|---|---|---|
| OAuthV2 | Security | Issue / validate OAuth 2 tokens. Supports all four grants. The workhorse for auth. |
| VerifyAPIKey | Security | Validate an API key from a header or query. Cheap, fast, tied to developer apps. |
| VerifyJWT / GenerateJWT | Security | JWT validation against JWKS, or signing your own. Replaces external JWT services. |
| BasicAuthentication | Security | Encode / decode Basic auth headers. Use sparingly. |
| Quota | Traffic | Long-window rate limits (per day/week/month). Tied to developer apps or API products. |
| SpikeArrest | Traffic | Short-window throttle (per second/minute). Smooths burst traffic. |
| ResponseCache / LookupCache / PopulateCache | Traffic | Response caching with TTL. Skip the backend for repeated identical reads. |
| AssignMessage | Mediation | The Swiss army knife — set/get headers, query, payload, variables. |
| ExtractVariables | Mediation | Pull values out of request/response into flow variables. Pair with AssignMessage. |
| JSONToXML / XMLToJSON | Mediation | Format conversion. Essential for REST↔SOAP bridges. |
| XSL | Mediation | XSLT transformation. Pre-X teams know this one painfully well. |
| JavaScript | Extension | Custom JS (Rhino-based on Edge, V8-style on X). Escape hatch for everything. |
| JavaCallout | Extension | Run Java code. Heavier than JS, useful for crypto and complex transformations. |
| ServiceCallout | Extension | Call out to another HTTP service mid-flow. Used for token validation, lookups, etc. |
| FlowCallout | Composition | Invoke a Shared Flow. The DRY mechanism for reused policies. |
| MessageLogging | Observability | Send structured logs to Splunk, Sumo, syslog, GCP Logging. |
| StatisticsCollector | Observability | Add custom dimensions to Apigee Analytics. |
| SemanticCacheLookup / SemanticCachePopulate / SanitizeUserPrompt / SanitizeModelResponse / LLMTokenQuota / PromptTokenLimit | AI / LLM | The AI policy family — semantic caching, prompt/response sanitization, and token-based quotas for LLM-backed proxies. |
▸ Watch out
JavaScript and JavaCallout costs add up. Use FlowCallout to compose policies before reaching for code.
Each JS execution adds 1–5 ms. Each JavaCallout adds 5–15 ms cold + JVM heap. Profile before you blame Apigee. The policy library exists so you don't write code.
03
DRY for APIs
Shared Flows & KVMs
Two Apigee features that nobody else does this well. They're how you stop repeating yourself across 200 API proxies.
Shared Flows
- Reusable policy chains invoked via FlowCallout from any proxy.
- Common patterns: auth-and-quota, logging-standard, cors-handling, error-formatter.
- Versioned independently — deploy once, all consumers get the update.
- Can compose multiple SharedFlows in sequence.
- Flow Hooks apply a SharedFlow to every proxy in an environment automatically.
Key Value Maps (KVMs)
- Org-, environment-, or apiproxy-scoped key-value store accessible from policies — apiproxy scope gives per-proxy isolation.
- Encrypted KVMs for secrets — never put credentials in proxy bundles.
- Use for: feature flags per env, target URL mappings, retry config, partner whitelist.
- Cached aggressively; updates may take minutes to propagate.
- Apigee X moves toward Property Sets for config; KVMs remain for runtime data.
▸ Pattern
"Pre-flow Shared Flow" pattern: auth + quota + logging + cors, mounted as Flow Hook.
Most mature Apigee deployments have a single org-wide pre-flow SharedFlow that runs on every proxy. It enforces baseline OAuth/JWT validation, default quota, structured logging, and CORS. Per-proxy policies layer on top. This is the right starting architecture.
04
How code becomes traffic
Environments & Revisions
Apigee separates code (proxy bundles) from where it runs (environments). A revision is an immutable snapshot of a proxy.
| Concept | What it is | Notes |
|---|---|---|
| Organization | Top-level Apigee instance. Maps to GCP project on X. | One per business unit, usually. |
| Environment | Runtime instance (eval / dev / test / prod / partner). | Routing rules, target URLs, KVMs all environment-scoped. |
| Environment Group | Apigee X — groups envs behind a single hostname. | Replaces Edge's "virtual hosts". |
| Revision | Immutable snapshot of a proxy bundle. | Save = new revision. Numbers monotonic. |
| Deployment | Mapping of revision → environment. | Deploy revision 7 to dev, revision 5 to prod = totally valid. |
| Proxy bundle | The exported ZIP of a proxy + policies + resources. | What CI/CD ships. |
▸ Common mistake
Treating environments like namespaces. They're runtime instances; promoting through them requires deploying revisions, not copying configs.
Mature setup:
apigee-cli or Apigee Maven plugin in CI, automatically deploys to dev → test → prod. The proxy bundle is the build artifact; environments are deployment targets. Don't manually copy-paste configs between envs — that's how policy drift happens.
05
What you actually pay
Pricing tiers
Apigee has two ways to pay: pay-as-you-go (per API call, no commitment) and subscription (a committed annual contract). Subscription is sold as capacity — it is not publicly bucketed by calls per day.
| Model | How it's billed | Indicative cost | Best for |
|---|---|---|---|
| Evaluation | 60-day trial organization, then deleted. | $0 | POCs only — not production, can't convert to paid. |
| Pay-as-you-go | Per API call ($20/M for Standard proxies, $100/M for Extensible), plus per-environment and per-deployment-unit charges. | Usage-based | Getting started, spiky or low traffic, no upfront commit. |
| Subscription · Standard | Committed annual capacity. Entry tier. | ~$6k/yr list | Single team, small public API. |
| Subscription · Enterprise | Committed annual capacity. Higher entitlements. | Negotiated | Mid-size; most common starting point. |
| Subscription · Enterprise Plus | Committed annual capacity. Top tier, full entitlements. | Negotiated | Large public APIs, multi-region SLA. |
| Hybrid runtime | Either model + your own K8s infrastructure cost. | + infra cost | On-prem / data residency. |
▸ Pricing reality
List price is a starting point — subscription deals are negotiated, and the published tiers don't expose a calls/day number.
Pay-as-you-go is the standard entry path: ~$20 per million calls to Standard proxies (~$500/mo at 15M calls/mo), plus per-environment and per-deployment-unit fees. Subscription tiers — Standard, Enterprise, Enterprise Plus — are sold on committed capacity, not a public per-call rate; Standard lists around ~$6k/yr but real contracts are negotiated. The dev portal, shared flows, and analytics come with the platform either way.
06
The honest summary
Strengths & Gotchas
What it does well
- Best-in-class developer portal, customizable, with auto-generated SmartDocs.
- Mature policy library covers ~90% of API patterns without writing code.
- Shared Flows + KVMs deliver DRY at scale. No other vendor has this exact UX.
- Strong analytics with custom dimensions, drill-down dashboards, anomaly detection.
- Hybrid is genuinely cloud-agnostic — control plane stays on GCP, runtime anywhere.
- Edge bundles export cleanly via API; CI/CD is solid.
What to watch for
- Adds up at small scale. Subscription Standard lists around ~$6k/yr, but per-environment and per-call charges stack on top; hard to justify for very low-traffic APIs.
- Steep learning curve. The policy DSL is its own world.
- Edge migration is non-trivial. Plan 12–24 months for >100 proxies.
- Hybrid adds K8s ops burden — you still manage runtime upgrades.
- Some Edge features still missing on X (improving each release).
- GCP-gravity. X works best in GCP. Multi-cloud teams gravitate to Hybrid or Kong.
07
In, out, and across
Migration paths
| Direction | Path | Effort |
|---|---|---|
| Edge → X | Export proxy bundles, recreate environments, redeploy KVMs, rewire dev portal. Most policies are compatible. | High · 12–24 months for >100 proxies |
| Edge → Hybrid | Similar to → X, plus K8s runtime setup. Pick when you need on-prem or data residency. | High |
| X → Hybrid | Adopt Hybrid runtime in your K8s; redeploy proxies. Control plane stays the same. | Medium |
| Apigee → Kong / Konnect | Rewrite policies as plugins, replatform dev portal, migrate KVMs to env vars / Vault. Plan 3–6 months/100 proxies. | High |
| Apigee → AWS API Gateway | Major regression in dev portal + shared flows. Only justified for cost-driven moves at small scale. | Very high |