Start with the big picture, in plain words.

The simple definition

An API, short for Application Programming Interface, is a doorway that lets one program talk to another program. When a weather app on your phone shows today’s forecast, it quietly sends a request through an API to a weather service and receives the answer. A backend is the service behind the doorway that actually holds the data or does the work.

Apigee is a full API management platform. It lets an organization design, secure, publish, monitor, and sell its APIs. Google acquired Apigee in 2016, and today it is offered as part of Google Cloud. In its most common form, you create API proxies, which are managed front doors that stand between the callers and your real backends. Every request goes through the proxy first, so Apigee can apply rules before anything reaches your valuable systems.

What it does in one list

• Secures APIs with keys, tokens, and threat checks.
• Controls traffic with limits, quotas, and caching.
• Transforms messages, such as converting one data format to another.
• Packages APIs into products that partners and developers can subscribe to.
• Publishes documentation and sign-up pages in a developer portal.
• Measures usage, speed, and errors with built-in analytics.
• Monetizes APIs when a company wants to charge for use.

Why it exists

As companies grew, they built dozens or hundreds of services. Each team added its own security checks, its own limits, and its own logging, and each did it a little differently. Partners and mobile apps struggled to connect. Apigee gives the organization one consistent layer where these shared concerns are handled once, in the same way, for every API.

To value a reception desk, picture the building without one.

HTTP, REST, and requests

HTTP is the language of the web. A program sends a request, such as “give me the list of orders for customer 42”, and receives a response, such as the list. REST is a popular style of designing APIs over HTTP, where each kind of thing, such as an order or a customer, has its own address and a small set of actions: read, create, change, and delete. Most modern APIs, including those Apigee manages, follow this style, though Apigee also supports others such as SOAP and GraphQL.

Microservices multiply the doors

A microservice is a small service that does one job. Companies split large systems into many microservices so that teams can work independently. The side effect is that the number of doors grows quickly. A shop that once had one big system may now have a hundred services, each with an API. If every door has its own lock design, nobody can keep them all safe.

What goes wrong without a managed layer

The API gateway idea

The common solution is an API gateway, a single entry point where all outside calls arrive first. The gateway applies shared rules and then forwards each approved call to the right service. Apigee is a gateway, but also much more: it adds product packaging, developer onboarding, analytics, and monetization on top of the gateway, which is why it is described as an API management platform and not just a gateway.

The vocabulary of the platform, explained one word at a time.

Organization

An organization is the top-level container in Apigee. It holds everything: proxies, products, developers, apps, analytics, and settings. In Apigee on Google Cloud, an organization is attached to one Google Cloud project, which carries the billing and the permissions.

Environment and environment group

An environment is a separate space inside the organization where proxies are deployed and run, such as “dev”, “test”, and “prod”. Each environment has its own settings, caches, and configuration values, so a mistake in test cannot touch production. An environment group is a set of one or more environments that share the same web addresses, called hostnames. A hostname is the name of the website that callers use, such as api.example.com. The group tells Apigee which environment should answer each hostname.

API proxy

An API proxy is the central building block. It is a bundle of configuration that tells Apigee how to receive a request on a public address, what to do to it, where to send it, and what to do with the reply. The word proxy means a stand-in: the proxy stands in for your backend toward the outside world.

Flow

A flow is an ordered pipeline of steps that a message follows as it passes through the proxy. There is a flow for the request on its way in and a flow for the response on its way out. Inside a flow, each step is a policy.

Policy

A policy is a ready-made building block that performs one specific job, such as “check the API key”, “limit calls to one hundred per minute”, or “convert this message from XML to JSON”. You attach policies to flows and tell Apigee in which order to run them. Policies are written as short configuration files, so for many jobs you need no programming at all.

Target endpoint

The target endpoint is the address of the real backend that the proxy forwards the request to. Many proxies have one target, but some have several or none at all, for example when the proxy itself builds a response.

API product

An API product is a bundle of API access packaged for consumers. It groups one or more proxies or paths, attaches a quota, defines which actions are allowed, and sets whether approval is automatic or manual. Developers subscribe to products, not to raw proxies. Think of a product as a subscription plan, such as “Basic plan: 1,000 calls per day”.

Developer, app, and credentials

A developer is a person or company that wants to use your APIs. An app is the program the developer builds, registered in Apigee. Each app receives credentials, usually a pair called a consumer key and a consumer secret. The app presents these when calling an API, so Apigee knows which app is calling and which products it may use.

Revision and deployment

Every time you save changes to a proxy, Apigee keeps a numbered revision. A revision is a frozen copy. You then deploy a chosen revision to an environment, which makes it live there. Because revisions are kept, you can roll back to an earlier one in moments if a new revision misbehaves.

Shared flow and flow hook

A shared flow is a reusable group of policies that many proxies can call, such as a standard security check. A flow hook attaches a shared flow to a fixed point in every proxy of an environment, so that rules like “always log every request” apply everywhere automatically.

Key value maps, caches, and target servers

A key value map, or KVM, is a small store of settings, such as an address or a threshold, that you can change without redeploying a proxy. A cache stores recent answers so that repeat requests are served quickly. A target server is a named backend address that proxies refer to by name, so you can point “orders-backend” at different addresses in test and production.

Two planes, one flow of traffic.

Apigee is built from two big parts. The control plane, also called the management plane, is where people configure things: they create proxies, products, and developers, and they view analytics. The runtime plane, also called the data plane, is where real API traffic is processed. Separating them means that a busy day of traffic does not slow down the screens where administrators work, and a configuration change is distributed to the runtime in a controlled way.

flowchart LR
  A["Client app or partner"] --> B["Global load balancer"]
  B --> C["Apigee runtime: router"]
  C --> D["Apigee runtime: message processor"]
  D --> E["Proxy request flow with policies"]
  E --> F["Target endpoint"]
  F --> G["Your backend service"]
  G --> H["Proxy response flow with policies"]
  H --> I["Response to client"]
  D --> J["Analytics and logging"]
  K["Admin in Cloud Console or API"] --> L["Apigee control plane"]
  L --> M["Deploys revisions and settings to runtime"]
  M --> D
    

Reading the diagram

Client app or partner. Any program that calls your API: a mobile app, a website, a partner system, or another internal service.

Global load balancer. In Apigee on Google Cloud, outside traffic usually arrives through a Google Cloud load balancer, which spreads the load, terminates secure connections, and can add protection such as Cloud Armor, Google’s web application firewall.

Router. The router looks at the hostname and the path, finds which environment and which proxy should handle the call, and passes the request along.

Message processor. This is the engine room. It runs the proxy’s flows: it executes each policy in order, calls the target, and builds the response.

Proxy request flow with policies. Security checks, limits, and transformations happen here, before any backend work.

Target endpoint and backend. If the request is approved, the proxy forwards it to the real service, which does the actual job.

Proxy response flow. On the way back, policies can reshape the response, remove sensitive fields, add headers, or store a copy in a cache.

Analytics and logging. Details of every call, such as who called, how long it took, and what status came back, are recorded asynchronously, which means they do not delay the response.

Control plane and deployment. Administrators work in the Cloud Console or through an API. When they deploy a revision, the control plane pushes it to the runtime for the chosen environment.

Same ideas, different homes for the runtime.

Over the years Apigee has been offered in several shapes. The names can be confusing, so here is a plain guide. Because Google updates its product lines, always confirm the current offerings and support status in the official documentation before planning a project.

Apigee X

Apigee X is the Google Cloud-native version. Both the control plane and the runtime run in Google Cloud. Google operates the runtime for you, in a project that Google manages on your behalf, and connects it to your own network. Your own backends can be anywhere that the runtime can reach: in Google Cloud, in another cloud, or in your own data center. Apigee X benefits from Google’s global network, its load balancers, and its security services.

Apigee hybrid

Apigee hybrid splits the platform. The control plane stays in Google Cloud, but the runtime plane runs in your own Kubernetes clusters, either in your data center or in any cloud you choose. Kubernetes is a system that runs and manages many containers. Hybrid suits organizations that must keep API traffic inside their own network for rules, speed, or data location reasons, while still using Google’s management screens and analytics.

Apigee Edge

Apigee Edge is the earlier generation of the platform, offered as a public cloud service and as a private installation. Many companies still run it. Google has encouraged moving to the newer generation, and you should check the current lifecycle and support notes when you plan any new work or migration.

flowchart TD
  A["Choosing a deployment model"] --> B{"Must API traffic stay in your own clusters or data center?"}
  B -- "Yes" --> C["Apigee hybrid"]
  B -- "No" --> D{"Already running Apigee Edge?"}
  D -- "Yes" --> E["Plan a move to Apigee X"]
  D -- "No" --> F["Apigee X"]
    

Connecting the network in Apigee X

Because the runtime lives in a Google-managed project, it needs a private road to your own network. Two common approaches exist. VPC peering connects your virtual network to the managed network so that they can exchange traffic privately. Private Service Connect provides a private doorway to the service without merging address ranges, which many organizations find simpler to manage. The choice affects how outside callers reach Apigee and how Apigee reaches your backends, so make it early. Check the current documentation for the recommended option for new setups.

Editions and cost shape

Apigee is offered with a free evaluation option for a limited time, and with paid options such as subscriptions and pay-as-you-go style billing, with different environment capabilities. Prices and packaging change, so read the current pricing page. The practical advice is to start with an evaluation organization for learning, and to size production by expected traffic and the number of environments.

Open one proxy and look at every part.

The two endpoints

Every proxy has two faces. The proxy endpoint faces the callers. It defines the base path, such as “/orders”, and what protocols it accepts. The target endpoint faces your backend. It defines the address where the proxy forwards requests. Between the two faces run the flows.

Flows in order

Within each endpoint, a message passes through a fixed series of stages. Understanding this order is the key to placing a policy correctly.

Conditions

A condition is a rule written as a short expression that decides whether a step or a flow runs. For example, a condition may say, “only when the path ends with /refunds and the verb is POST”. Conditions let one proxy behave differently for different operations without being split into many proxies.

Flow variables

As a message travels, Apigee keeps a bag of named values called flow variables. They include things like the caller’s app name, the request’s path, the time of the request, and the response’s status code. Policies read and write these variables to pass information to later steps. This is how a security policy can tell a later logging policy which developer made the call.

Fault handling

When a policy fails, for example because a key is invalid, Apigee raises a fault. A fault stops the normal flow and jumps to fault rules, which you design to return a clear, friendly error message to the caller and to log what happened. Without fault rules, callers may see confusing default messages that expose internal details.

Proxy versus target-only designs

Most proxies forward to a backend. Some proxies are no-target proxies, which build the answer themselves, for example to return a fixed message or to combine data from several services collected through service callout policies.

flowchart TD
  A["Request arrives at proxy endpoint"] --> B["PreFlow: verify credentials and apply limits"]
  B --> C{"Condition matches?"}
  C -- "Path orders and verb GET" --> D["Conditional flow: get orders"]
  C -- "Path orders and verb POST" --> E["Conditional flow: create order"]
  D --> F["PostFlow"]
  E --> F
  F --> G["Target endpoint: call backend"]
  G --> H["Target response flow"]
  H --> I["Proxy response flow: shape and cache"]
  I --> J["Response to caller"]
  B -- "Policy fails" --> K["Fault rules return friendly error"]
    

The toolbox that makes Apigee powerful without programming.

Apigee offers many dozens of policies. They fall into a few families. You do not need to memorize them. You need to know the families so that you can find the right tool for a job.

Traffic management policies

These protect your backends and keep usage fair. Spike Arrest smooths bursts, so that a sudden flood is slowed down before it hits the backend. Quota counts calls over a longer period, such as per day or per month, and refuses extras once the limit is reached. Concurrent Rate Limit caps how many calls to a backend may be in progress at once. Response Cache stores replies so repeat requests are answered instantly, saving backend work.

Security policies

Verify API Key checks that the caller presented a valid key. OAuth v2 policies issue and verify access tokens. Verify JWT and Generate JWT work with JSON Web Tokens, a compact signed way of carrying identity. JSON Threat Protection and XML Threat Protection reject messages that are suspiciously deep, huge, or malformed, which are common tricks of attackers. Access Control allows or blocks callers by network address. Others handle encrypted content and the security of the backend connection.

Mediation policies

Mediation means translating between what callers want and what backends offer. Assign Message creates or changes parts of a message, such as headers and parameters. Extract Variables pulls values out of a message into flow variables. JSON to XML and XML to JSON convert formats. Raise Fault deliberately returns a custom error. Key Value Map Operations read and write configuration stored in KVMs.

Extension policies

When the built-in steps are not enough, extension policies let you add your own logic. JavaScript runs short scripts. Java Callout runs compiled Java code. Service Callout calls another service during the flow and uses its answer. Message Logging sends details to a logging system. Use extensions sparingly, because every custom script is something your team must maintain and test.

Spike Arrest versus Quota

Beginners often confuse these two. They solve different problems. Spike Arrest protects against sudden bursts over very short moments, like a doorman who lets people in at an even pace so that no stampede forms. Quota enforces a total allowance over a longer period, like a gym membership that allows a fixed number of visits per month. Most production proxies use both.

Layered defenses for the most exposed part of your system.

An API gateway sits on the edge of your world, facing the open internet. That makes it a prime target, and also the best place to defend. Good security here comes in layers, like the locks, cameras, and guards of a bank.

Layer one: the network edge

Put a Google Cloud load balancer in front of Apigee and attach Cloud Armor, a web application firewall and distributed denial-of-service shield. A denial-of-service attack tries to take a service down by overwhelming it with traffic. Cloud Armor can block bad addresses, countries, and known attack patterns before they reach Apigee. Use secure connections everywhere, so traffic is encrypted in transit. For stricter needs, mutual TLS, shortened to mTLS, makes both sides present certificates, so the server also checks the caller’s identity.

Layer two: identity of the caller

Apigee supports several ways to identify callers.

An API key identifies the app, but a key can be copied. OAuth tokens are shorter lived and can carry limited permissions called scopes, such as “read orders but not delete them”. For anything touching private user data or money, prefer OAuth or JWT with scopes, and use keys only to identify apps.

Layer three: message protection

Use threat protection policies to reject messages that are unusually large, deeply nested, or contain risky patterns. Validate input where you can: reject a request early if a required field is missing or its type is wrong. Do not forward everything blindly to your backend and hope it copes.

Layer four: protecting the backend

The proxy should not just hide the backend’s address. It should make the backend refuse direct calls from anyone else. Use mutual TLS, private networking, or a shared credential that the proxy adds, so that only Apigee can reach the backend. Otherwise an attacker who learns the backend’s address can bypass every rule you built.

Layer five: abuse detection and advanced security

Apigee offers Advanced API Security, which can score your proxies’ configuration for weaknesses and detect unusual traffic patterns that suggest abuse, such as a bot scraping data. Check the current documentation for exact capabilities and availability in your edition.

Layer six: administrative security

Protect the control plane as strictly as the data plane. Use Google Cloud IAM, Identity and Access Management, to give people only the roles they need: some may only view analytics, others may deploy to test but not to production. Apigee provides predefined roles for administrators, API developers, environment administrators, and analytics viewers. Use customer-managed encryption keys when your policies require control over the keys that protect stored data, and VPC Service Controls to draw a protective boundary around the service where supported.

Secrets and sensitive values

Store backend passwords, keys, and certificates in encrypted key value maps or in Secret Manager, never in plain text inside proxy files that get copied around in code repositories.

flowchart TD
  A["Internet caller"] --> B["Cloud Armor and load balancer"]
  B --> C["Apigee: verify key or token"]
  C --> D["Apigee: spike arrest and quota"]
  D --> E["Apigee: threat protection and input checks"]
  E --> F["Private or mutual TLS connection"]
  F --> G["Backend accepts only Apigee"]
  C -- "Invalid" --> X["Reject with friendly error"]
  D -- "Over limit" --> X
  E -- "Malformed" --> X
    

Keep backends healthy, callers fair, and answers fast.

Why traffic needs shaping

Traffic is rarely smooth. It arrives in waves: a marketing email lands, a sale starts, a partner runs a nightly batch. Backends are built for a normal load, and a sudden wave can overwhelm them. Traffic management is the set of tools that turns wild waves into a flow the backend can digest.

Spike arrest: smoothing the burst

The spike arrest policy does not count calls in a bucket and reset it. Instead it spreads the allowed rate evenly across time. If you set ten calls per second, the policy allows roughly one call every tenth of a second. A caller who sends ten calls in the first millisecond finds that most are rejected, even though ten per second in total would have been fine. This smoothing is exactly what protects a delicate backend. Callers who exceed the rate receive a clear error telling them to slow down.

Quota: counting the allowance

The quota policy keeps a counter. Each call increments it, and when the counter reaches the limit for the period, further calls are rejected until the period resets. You can count per app, per developer, per product, or per any value you choose. You can also set quotas that are distributed across all message processors, so the count stays accurate across the whole cluster, with a tradeoff in speed. Quota settings are often placed on the API product, so each plan gets its own allowance.

Caching: the fastest call is the one you do not make

A cache keeps a copy of a recent answer. The next caller who asks the same question gets the stored copy instantly, without bothering the backend. This is especially valuable for data that changes slowly, such as a product catalog or a list of store locations. You decide the cache key, which is the combination of values that identifies “the same question”, and a time to live, which is how long the copy is kept. Be careful: never cache answers that contain private data for one user and then show them to another. Include the user identity in the cache key or skip caching for personal data.

Load balancing to several backends

A target endpoint can point to a named target server list. Apigee can spread requests over several backends using rules such as round robin, weighted, or least connections. It can also run health checks, which are small test calls that confirm each backend is alive, and it can stop sending traffic to a backend that fails. This gives you high availability without extra hardware.

Timeouts and retries

A timeout is the longest the proxy will wait for the backend. Without a timeout, a stuck backend ties up the gateway’s resources while callers wait forever. Set timeouts that match the real behavior of each backend, with some margin. A retry sends the request again after a failure. Retrying is safe only for operations that can be repeated without harm, such as reading data. Retrying a payment could charge a customer twice, so use retries carefully and only for safe operations.

Circuit breaking by design

A circuit breaker is a pattern that stops sending traffic to a failing backend for a short time, giving it a chance to recover, and returns a quick error or a cached fallback in the meantime. With health monitors, error handling, and conditional logic, you can build this behavior in Apigee. The goal is to fail fast and politely, not to pile more load on a struggling service.

Graceful degradation

When the backend is down, the proxy can serve a stale cached copy, return a simplified answer, or give a clear message with a “try again later” hint. Callers prefer a clear, quick message over a long hang.

flowchart TD
  A["Request arrives"] --> B["Spike arrest: within rate?"]
  B -- "No" --> X1["Reject: slow down"]
  B -- "Yes" --> C["Verify identity"]
  C --> D["Quota: within plan allowance?"]
  D -- "No" --> X2["Reject: quota exceeded"]
  D -- "Yes" --> E{"Cached answer available?"}
  E -- "Yes" --> F["Return cached answer"]
  E -- "No" --> G["Pick healthy backend"]
  G --> H["Call backend with timeout"]
  H -- "Success" --> I["Store in cache and respond"]
  H -- "Failure" --> J["Serve fallback or friendly error"]
    

Turn a technical doorway into something people can actually sign up for.

From proxy to product

A proxy is a technical thing. An API product is a business thing. A product answers questions such as: Which operations are included? How many calls are allowed per day? Do you need approval? What does it cost? By bundling proxies into products, you decide how to offer your APIs, not just how to build them. One proxy can appear in several products with different limits, such as “Free”, “Standard”, and “Enterprise”.

Developers and apps

A developer registers, creates one or more apps, and requests access to products. When approved, the app receives credentials tied to those products. Every call the app makes carries the credentials, and the proxy uses them to decide the allowance, the permissions, and the analytics label. This is how you can answer, “Which partner used the most calls last month?”

Approval flows

For public or low-risk APIs, approval can be automatic. For sensitive APIs, it can be manual: a person from your team reviews each request before the app can use the product. You can also revoke an app’s access at any time without touching the proxy, which is a powerful safety lever.

The developer portal

A developer portal is a website where outside developers read documentation, try the APIs, register apps, request access, and view their own usage. Apigee provides an integrated portal that you can customize with your own branding and pages, and also supports building a fully custom one by using Apigee’s management interfaces. Good documentation is part of the product. An API that nobody understands is not used.

API specifications and documentation

An OpenAPI specification is a standard file that describes an API’s paths, inputs, and outputs in a machine-readable way. Apigee can import specifications to create proxies and publish interactive documentation, where a developer can read about each call and try it directly. A single specification then serves as both the design contract and the documentation.

Monetization

Some companies charge for API use. Apigee offers monetization features that let you define rate plans, such as a monthly fee, a price per call, or tiered pricing, and produce usage records and billing information. Not every organization needs this, and its availability can vary by edition, so check the current documentation.

API lifecycle

sequenceDiagram
  participant Dev as "External developer"
  participant Portal as "Developer portal"
  participant Apg as "Apigee management"
  participant Admin as "API team"
  participant Run as "Apigee runtime"
  Dev->>Portal: "Register and create an app"
  Portal->>Apg: "Create developer and app"
  Dev->>Portal: "Request access to a product"
  Portal->>Apg: "Add product to app"
  Apg-->>Admin: "Approval needed"
  Admin->>Apg: "Approve"
  Apg-->>Dev: "Credentials issued"
  Dev->>Run: "Call API with key or token"
  Run->>Run: "Verify credentials and apply product quota"
  Run-->>Dev: "Response"
    

A calm, ordered path that avoids the usual surprises.

Step one: prepare a Google Cloud project

Choose or create a Google Cloud project with billing set up. Enable the Apigee API and the other services that the setup wizard asks for. For learning, you can start with an evaluation organization, which Google offers for a limited time, so that you can explore without a long-term commitment. Always read the current terms before you start.

Step two: provision the organization

Provisioning creates the Apigee organization in your project, along with a runtime instance in a chosen region and the network connection described earlier. This step can take a while, often many minutes, because real infrastructure is being created. Choose the region close to your backends and your callers, and choose the analytics region that matches your data rules.

Step three: create an environment and an environment group

Create at least a test environment and attach it to an environment group with a hostname. For quick learning, many setups use a wildcard hostname based on a free address service. For anything real, use your own domain and a proper certificate.

Step four: expose the runtime to callers

Connect callers to the runtime by setting up a Google Cloud external load balancer, which will accept the secure connections from the internet and forward them to Apigee, or by using the internal route for private callers. The provisioning wizard can create a standard setup for you.

Step five: create your first proxy

In the Cloud Console, open Apigee, choose to create a proxy, and pick a type. A reverse proxy forwards to an existing backend. Give it a name, a base path, and a target address. A simple public test service is enough for practice. Add a Verify API Key policy and a Spike Arrest policy to its PreFlow.

Step six: deploy and test

Deploy the revision to your test environment. Use the built-in debug tool to start a debug session, which records every step of each request that passes through the proxy, then send a call from a web browser or a command-line tool. Read the trace to see each policy and its result.

Step seven: create a product, a developer, and an app

Create an API product that includes your proxy, create a test developer, and create an app that subscribes to the product. Use the app’s key in your test call to confirm that security and quota work as intended.

Tools for working

• Cloud Console: the visual place for creating proxies, viewing analytics, and managing products.
• Management APIs: let scripts and pipelines create and change every object.
• Command-line helpers and plugins: community and official tools that import and deploy bundles from files, ideal for pipelines.
• Infrastructure as code: tools that define organizations, environments, and settings as reviewed files.

Follow a single call from the caller’s phone to the backend and back.

Step by step

Imagine a mobile app asks for the list of orders of customer 42. Here is what happens, in plain words.

1. The caller connects. The app opens a secure connection to the API’s hostname. The load balancer terminates the secure connection and inspects it using Cloud Armor rules.

2. Routing. The request reaches the Apigee runtime. The router matches the hostname to an environment group, then the environment, then the proxy whose base path matches the start of the request path.

3. Proxy request flow starts. The message processor creates a message context, a working area that holds the request, the response to be built, and all the flow variables.

4. Security and limits. The Verify API Key or OAuth policy reads the credential from the request, looks it up, and if valid, writes details about the app, developer, and product into flow variables. The spike arrest and quota policies then run, using those variables.

5. Mediation. Other policies may rename parameters, add headers, or build a request that the backend understands. Perhaps the backend expects a different path or an internal credential, which a policy adds.

6. Target call. The message processor sends the request to the target, applying the connection and read timeouts. The backend does its work and answers.

7. Response processing. Response policies may remove internal fields, convert the format, and store the answer in a cache.

8. Reply. The response is sent back through the load balancer to the caller.

9. Analytics. After the reply is on its way, the details of the call, such as status code, response time, app, and product, are written to the analytics pipeline in the background.

sequenceDiagram
  participant C as "Mobile app"
  participant LB as "Load balancer"
  participant R as "Apigee router"
  participant MP as "Message processor"
  participant B as "Backend service"
  participant A as "Analytics"
  C->>LB: "GET orders for customer 42"
  LB->>R: "Forward after edge checks"
  R->>MP: "Route to proxy and environment"
  MP->>MP: "Verify credential and load app details"
  MP->>MP: "Spike arrest and quota checks"
  MP->>B: "Forward adjusted request with timeout"
  B-->>MP: "Order list"
  MP->>MP: "Shape response and update cache"
  MP-->>LB: "Response"
  LB-->>C: "Response"
  MP-)A: "Record call details in background"
    

What happens when something fails

If a policy fails, Apigee jumps to the fault rules. A default fault rule can build a clean error message in a standard format, such as a status code and a short explanation, hiding internal details. The fault is recorded in analytics too, so that error rates can be measured per app, per product, and per proxy.

Statelessness and scaling

Each message processor handles requests independently. Shared state, such as quota counters and caches, lives in a separate data layer. This design lets Apigee add processors to handle more traffic, and lets any processor serve any call.

Configuration distribution

When you deploy a revision, the control plane sends the proxy’s bundle to the runtime for the chosen environment. Message processors load it without restarting. For a short moment, an old revision and a new one may both exist, but a request is processed fully by one revision. Applying a new revision does not break a call that is already in progress.

When something breaks, ask the right questions in the right order.

What you can measure

Because every call passes through Apigee, it can record rich facts about each one: which app called, which product, which proxy, which path and verb, how long it took, how big it was, and what status came back. These facts feed built-in dashboards that answer questions such as: Which APIs are most used? Which apps cause the most errors? Which partner’s traffic is growing fastest? How fast is each backend? You can also build custom reports with the dimensions and measures that matter to your business.

Key numbers to watch

Proxy latency versus target latency

Apigee separates the time spent inside the gateway from the time spent waiting for the backend. This helps assign responsibility: if the total time is high but the target time is low, your own policies or scripts are slow. If the target time is high, the backend is the problem. Without this split, teams argue about whose fault slowness is.

Debug sessions

A debug session, also called a trace, records the full journey of live requests through a proxy: each policy that ran, each flow variable’s value, the request and the response at each stage, and any error. It is the single best tool for learning and for solving puzzles. Because debug data can include sensitive values, restrict who may use it, and mask fields such as passwords and card numbers.

API monitoring and alerting

Apigee includes monitoring features that show the health of APIs near real time and let you create alerts, for example when the error rate for a proxy exceeds a threshold or the response time grows. Alerts can notify email, chat systems, or incident tools. You can also use Google Cloud’s Cloud Monitoring and Cloud Logging, which receive metrics and logs from the platform, so that API health sits next to the health of the rest of your cloud.

Logging

The message logging policy can send selected details to a logging destination. Log only what you need, such as request identifiers, status, and timings, and never log secrets or full personal data. A good practice is to create a correlation identifier, a unique code attached to each request at the front door and passed to every backend, so that one call can be traced through all systems by searching for that code.

A troubleshooting checklist

Change APIs safely without surprising the people who rely on them.

Revisions and deployments

Each saved change to a proxy creates a new numbered revision. Deploying a revision to an environment makes it live there. Because earlier revisions remain stored, rolling back is simply deploying the older revision again. Apigee also supports deployments that avoid downtime, where the new revision is brought up and traffic switches over without dropping calls in progress.

Promoting through environments

A healthy path goes from development to test to production. The same proxy bundle moves forward, with environment-specific values, such as backend addresses and secrets, kept outside the bundle in target servers and key value maps. This way the code you tested is exactly the code you release.

Versioning your API

Callers depend on your API’s shape. If you rename a field, you can break every app. A breaking change is one that makes old callers fail. To avoid chaos, give your API versions, such as /v1 and /v2, in the base path. Keep the old version running while consumers migrate, announce a retirement date, and measure old-version traffic in analytics so that you know when it is safe to switch it off. Prefer additive changes, such as adding an optional field, which do not break anyone.

Continuous integration and delivery

CI/CD is an automated factory line for software: Continuous Integration builds and tests every change, and Continuous Delivery ships it. For Apigee, a pipeline typically does the following: checks the proxy files for style and common mistakes using a lint tool, runs unit tests on scripts, deploys the bundle to a test environment, runs automated API tests against it, and, on success and approval, deploys to production. Cloud Build, GitHub Actions, and Jenkins are common ways to run these pipelines.

Testing proxies

• Static checks: catch unused policies and missing error handling before deployment.
• Unit tests: test custom scripts without the gateway.
• Functional tests: call the deployed proxy and check responses for each operation, including error cases.
• Security tests: confirm that calls without keys, with expired tokens, or with oversized bodies are rejected.
• Load tests: confirm that limits and caches behave under pressure.

Managing configuration as code

Keep proxy bundles, shared flows, products, and environment settings in a source repository. Review changes through pull requests. A common rule is that nobody edits production by hand. If it is not in the repository, it does not exist.

flowchart LR
  A["Developer commits proxy changes"] --> B["Pipeline: lint and unit tests"]
  B --> C["Deploy revision to test environment"]
  C --> D["Automated API tests"]
  D --> E{"All checks pass?"}
  E -- "No" --> F["Stop and report"]
  E -- "Yes" --> G["Manual approval"]
  G --> H["Deploy same bundle to production"]
  H --> I["Monitor errors and latency"]
  I -- "Problem found" --> J["Redeploy previous revision"]
    

An honest look at when Apigee is the right tool, and when it is not.

Apigee versus other options

A useful rule: if you have a handful of internal APIs and no outside developers, a simple gateway or load balancer may be enough. If you have many APIs, external partners, or a need to measure and govern usage, a full platform pays for itself. Many large organizations use both: Apigee at the outer edge for partners and apps, and a service mesh inside for service-to-service traffic.

What does the front desk cost, and how much crowd can it handle?

The cost of the extra hop

Any gateway adds some time to every call, because the message passes through another system and runs policies. Well-designed proxies add only a small amount, often a few milliseconds to tens of milliseconds, depending on the policies used and the distance between the gateway and the backend. Heavy scripts, large body transformations, and chains of service callouts add more. Measure the added time in your own environment, and keep proxies lean.

Keep policies lean

• Prefer built-in policies over custom scripts when both can do the job.
• Avoid parsing very large message bodies in scripts.
• Avoid unnecessary service callouts. Each is another network trip.
• Cache results of slow lookups, such as token validation or reference data.
• Place the cheapest rejecting policies first.

Scaling

In Apigee X, you size the runtime by choosing the number of nodes, the capacity of the instance, and the environment type. The runtime can scale as traffic grows, within the limits of the chosen configuration and edition. In hybrid, you scale your own Kubernetes clusters and the runtime’s pods. Because message processors are stateless for each request, adding capacity is mostly a matter of adding more of them.

Availability

For high availability, run the runtime in more than one zone within a region, which Apigee does by default in many setups, and consider using more than one region for critical APIs, with a global load balancer directing traffic to the closest healthy region. Backends must also be highly available, because a perfect gateway in front of a single fragile backend still fails. Test failure scenarios on purpose: shut down a backend in a test environment and confirm that the proxy returns the fallback response you designed.

Understanding the bill

Pricing details change, so use Google’s pricing page as the authority. In general, the cost depends on the edition or subscription tier, the number and type of environments, the amount of runtime capacity, the volume of API calls, and optional features such as advanced security, monetization, or additional analytics. There may also be costs from the surrounding Google Cloud services, such as load balancers, network egress, and logging storage.

Practical cost control

• Use one non-production organization or fewer environments for learning and testing.
• Right-size the runtime to real traffic, and review it after peak seasons.
• Cache aggressively where it is safe, to reduce backend and gateway work.
• Set log retention sensibly and avoid logging whole message bodies.
• Retire unused proxies and products regularly.

flowchart TD
  A["Users in many regions"] --> B["Global load balancer"]
  B --> C["Apigee instance in region one"]
  B --> D["Apigee instance in region two"]
  C --> E["Backends in region one"]
  D --> F["Backends in region two"]
  C -. "Failover if region one is unhealthy" .-> F
  D -. "Failover if region two is unhealthy" .-> E
    

Habits that help, and habits that hurt.

Helpful patterns

Anti-patterns to avoid

A short, practical rulebook you can pin to the wall.

Best practices

• Design the API first. Write the specification, agree on names and error shapes with consumers, then build the proxy.
• Put cheap protective policies first. Spike arrest and identity checks come before any expensive work.
• Use OAuth or JWT for user data. Use scopes so that each token can do only what it must.
• Lock the backend to the gateway. Private networking or mutual TLS so nobody can bypass the front door.
• Define consistent fault rules. Every proxy returns the same clean error shape.
• Keep proxies small and focused. One business capability per proxy, with a named owner.
• Reuse shared flows. Security and logging live in one place and apply everywhere.
• Separate environments properly. Keep addresses, secrets, and settings outside the bundle.
• Automate delivery. Lint, test, deploy through pipelines, and keep a rollback path.
• Version APIs and plan retirement. Announce changes, measure old-version traffic, and switch off with notice.
• Mask sensitive data in logs and traces. Never store secrets or full personal data.
• Monitor errors, latency, and limits. Alert on trends before callers complain.
• Document for humans. Provide examples, error lists, and a place to ask questions.
• Review access regularly. Remove stale administrators, developers, and apps.

Common mistakes beginners make

How different organizations put the reception desk to work.

flowchart TD
  A["Web, mobile, and partner apps"] --> B["Cloud Armor and load balancer"]
  B --> C["Apigee: security, limits, mediation"]
  C --> D["Orders service"]
  C --> E["Catalog service"]
  C --> F["Legacy inventory system"]
  C --> G["Analytics and monitoring"]
  H["Developer portal"] --> I["Apigee management: products and apps"]
  I --> C
  J["CI/CD pipeline"] --> I
    

Notice what these stories share. Apigee is not just a technical gateway. It is the place where an organization decides how its digital doors work: who may enter, how fast, with which plan, and how the visits are measured. The tool is powerful. The habits around it, such as design first, automation, and measurement, are what create lasting value.

Quick answers to the questions beginners ask most.

It is Google Cloud’s API management platform that sits in front of your backend services to secure, control, measure, package, and publish your APIs.

It is a managed front door for a backend. It receives calls, applies policies, forwards approved calls to the backend, and processes the reply on the way back.

A policy is a ready-made rule step, such as verifying a key, limiting calls, converting a format, or caching a reply. You attach policies to flows without writing a full program.

Spike Arrest smooths short bursts by spacing calls evenly. Quota counts calls over a longer period, such as a day or month, and enforces a plan allowance. Most proxies use both.

It is a bundle of API access with limits and rules, offered to developers like a plan. Developers’ apps subscribe to products and receive credentials.

In Apigee X, Google operates the runtime in Google Cloud. In hybrid, the control plane runs in Google Cloud but the runtime runs in your own Kubernetes clusters. Check the current documentation for details and support status.

Often no. Many jobs can be done with built-in policies. For special cases, you can add scripts or callouts, but keep them small and well tested.

Use keys mainly to identify apps for limits and analytics. For private user data or money, use OAuth or JWT with scopes. Many APIs use both together.

It is a set of environments that share hostnames. It tells Apigee which environment should answer requests sent to a given web address.

Start a debug session, send a request, and read each step and variable. The failing policy and its message are usually clear. Mask sensitive values and limit who can use debug sessions.

Redeploy the previous revision to the environment. Because revisions are kept, rollback is quick. Investigate after traffic is healthy again.

It adds a small amount of time because requests pass through another layer. Lean proxies keep this small, and caching can make some calls faster than calling the backend directly. Measure it with your own policies and backends.

Yes. Backends can be in other clouds or in your own data center, as long as the runtime can reach them over a secure, private, or public network path that you design.

Pricing depends on the edition, capacity, environments, call volume, and optional features, and it changes over time. Check Google’s pricing page and consider using the evaluation option while learning.

If you have a few internal APIs, no outside developers, and no need for products, portals, or detailed analytics, a simpler option such as API Gateway or a load balancer may be enough.

Everything important, in one place.