Apigee Fundamentals: Architecture and Request Flow

The request lifecycle

Now the central picture. A proxy has a proxy endpoint (how clients call it: the base path and connection settings) and a target endpoint (how Apigee calls the backend: URL, security and connection settings). Each endpoint has a request side and a response side, built from the same flow segments.

The flow segments, as the documentation defines them:

• PreFlow runs first, every time. It is the right place for checks that must always happen, such as verifying a key.
• Conditional flows run next. Each has a <Condition> built from flow variables. Only one runs per segment: the first whose condition is true. The condition is evaluated once and applies to both request and response.
• PostFlow runs after the conditional flows. Use it for logging or response shaping.
• PostClientFlow exists only on the proxy endpoint and runs after the response has been sent to the client. It allows only a small set of policy types (FlowCallout, MessageLogging, ServiceCallout) and is meant for final logging.

The full order on the way in is: proxy PreFlow, proxy conditional flow, proxy PostFlow, then (after the RouteRule picks a target) target PreFlow, target conditional flow, target PostFlow, then the call to the backend. The response comes back through the target response flows, then the proxy response flows. Note that the proxy endpoint's PostFlow finishes before the target endpoint's PreFlow begins.

How to read it: the notes mark where your policies can run. If a request fails in a policy, Apigee stops the normal pipeline and enters fault handling (lesson 7 covers it). A step in a flow can also carry its own condition, and a RaiseFault step can deliberately fail a request.

The RouteRule decides which target the request goes to. The documentation lists four shapes: a named target endpoint, a direct URL (no target endpoint file, so only proxy endpoint flows can hold policies), conditional rules that choose among several targets, and a null route that calls no backend and lets the proxy build the response itself. The first matching rule wins, so put conditional rules first and the unconditional default last.

Flow variables and the message model

Policies do not pass data to each other directly. They read and write flow variables: named values that hold the state of one API transaction. Apigee fills in many of them automatically (request details, system values, the target's response), and policies add more as they run (for example the app name after a key check).

A few built-in variables from the reference, with their documented meaning:

Two rules save a lot of debugging. First, variables have a scope: reading one before the point where it is populated gives null or an error (the response variable, for example, exists only from the target response onward). Second, the syntax differs by context: inside a policy you write the name in braces ({client.ip}), and inside a <Condition> you write it bare (request.verb = "POST"). In JavaScript policies you use context.getVariable() and context.setVariable().

A minimal proxy as files

An API proxy is a bundle of XML files. This minimal outline shows the proxy endpoint, one policy in the PreFlow, and the route. The four snippets below are, in order, apiproxy/proxies/default.xml, apiproxy/policies/VA-VerifyKey.xml, apiproxy/policies/AM-AddAppHeader.xml and apiproxy/targets/default.xml. The proxy endpoint verifies the key first and routes to the target; the target endpoint calls the backend after adding a header.

<ProxyEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request>
      <Step><Name>VA-VerifyKey</Name></Step>
    </Request>
    <Response/>
  </PreFlow>
  <HTTPProxyConnection>
    <BasePath>/orders-api/v1</BasePath>
  </HTTPProxyConnection>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

<VerifyAPIKey name="VA-VerifyKey">
  <APIKey ref="request.header.x-api-key"/>
</VerifyAPIKey>

The key comes from a header on purpose: the VerifyAPIKey reference notes that putting the key in a header is the better practice. On success the policy sets flow variables prefixed verifyapikey.VA-VerifyKey, including client_id, developer.app.name and apiproduct.name. A failed check returns a 401 for faults such as oauth.v2.InvalidApiKey and oauth.v2.FailedToResolveAPIKey.

Those variables make the next policy possible: pass the caller's app name to the backend as a header, and strip the credential before the call leaves Apigee.

<AssignMessage name="AM-AddAppHeader">
  <Remove>
    <Headers>
      <Header name="x-api-key"/>
    </Headers>
  </Remove>
  <Set>
    <Headers>
      <Header name="x-client-app">{verifyapikey.VA-VerifyKey.developer.app.name}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo>request</AssignTo>
</AssignMessage>

<TargetEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request>
      <Step><Name>AM-AddAppHeader</Name></Step>
    </Request>
    <Response/>
  </PreFlow>
  <HTTPTargetConnection>
    <URL>https://mocktarget.apigee.net</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

Actions inside one AssignMessage run in the order written, so Remove before Set is deliberate. mocktarget.apigee.net is the hosted mock service that Apigee's own getting-started guide uses as a target.

Proxy, product, developer app and credentials

Four objects, four jobs. Keep them apart and most access-control questions answer themselves.

The documentation stresses a point that is easy to miss: API keys are issued for API products, not for APIs. When a call arrives, Apigee checks the credential, finds the products attached to it, confirms the proxy, path and method are allowed, checks quota, and confirms the key, app and developer are active and not revoked. Two consequences are security-critical:

• A proxy must actually verify. Products grant access, but nothing is enforced unless the proxy contains a VerifyAPIKey or VerifyAccessToken step. Without one, any caller can invoke the API.
• Product scope matters. The documentation says that if no environments are specified, all environments are allowed by the product. For proxies, always list the ones the product covers rather than relying on a default.

A quota set on a product does not enforce itself either. It is a default that a Quota policy reads (through variables such as verifyapikey.<policy>.apiproduct.developer.quota.limit), and the verification policy must run before the Quota policy.

How to read it: access runs from developer to app to product to operation to proxy. A revision is a numbered snapshot of a proxy's configuration; revision numbers are internal and unrelated to your public API version.

Apigee, Apigee hybrid and Edge

Google's documentation presents two current deployment options: Apigee (cloud-hosted; Google maintains the environment) and Apigee hybrid (a runtime plane that you install on-premises or in your chosen cloud, paired with a management plane hosted in Google's cloud). Older pages and the Edge migration pages call the cloud-hosted product Apigee X, and this course uses that name where it helps. Apigee Edge is the previous generation, documented separately (Public Cloud as hosted SaaS, Private Cloud as an on-premises install).

A few documented migration differences from the Edge-to-X comparison page, because they bite during moves: roles move to Google Cloud IAM, Node.js proxies and hosted targets are not supported in X, the StatisticsCollector policy is replaced by DataCapture, and trace in X is asynchronous with a slight delay while Edge trace is real time. The same page lists limits that differ between the two products, so check the limits pages for the product you run. Concepts in this course carry across all variants; examples target the cloud-hosted product.

Analytics at a glance

For every call Apigee records default data, including the URL, IP address and user ID. Policies can capture more (headers, query parameters, or fields taken from the body). Collection is asynchronous, so it does not slow the API. You read the results as trends and reports in the Apigee UI, or fetch them through the Analytics Service by command line or REST. Lesson 7 returns to this for monitoring and troubleshooting.

Hands-on: your first proxy, product and app

This sequence uses an evaluation organization (see the course overview for how to get one) and the hosted mock backend, so there is nothing to build before you start.

1. Create the proxy. In the Google Cloud console go to Apigee, then Proxy development, then API proxies, and click Create. Pick the "Reverse proxy (Most common)" template, name it orders-api, and set the target to https://mocktarget.apigee.net. The console fills the base path from the name; set it to /orders-api/v1 if you want it to match this lesson.
2. Add the policies. Add the VA-VerifyKey step in the proxy endpoint PreFlow and AM-AddAppHeader in the target endpoint PreFlow, using the XML above.
3. Deploy the revision to your evaluation environment and note the hostname of its environment group (the evaluation wizard names the group eval-group and the environment eval, and creates a hello-world proxy you can call first).
4. Create a product, developer and app with the Apigee API. The shell below assumes gcloud is signed in and ORG is your project ID:

TOKEN=$(gcloud auth print-access-token)
ORG=my-project-id            # the Apigee organization name equals the project ID
BASE=https://apigee.googleapis.com/v1/organizations/$ORG

# 1) API product: allow the proxy in the eval environment. Quota fields are strings in the API.
curl -s -X POST "$BASE/apiproducts" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"partner-basic","displayName":"Partner Basic","approvalType":"auto",
       "environments":["eval"],"proxies":["orders-api"],
       "quota":"100","quotaInterval":"1","quotaTimeUnit":"minute"}'

# 2) Developer (email must be lowercase)
curl -s -X POST "$BASE/developers" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"email":"dev@example.com","firstName":"Test","lastName":"Developer","userName":"testdev"}'

# 3) App tied to the product; Apigee generates a key. Read credentials[].consumerKey in the response.
curl -s -X POST "$BASE/developers/dev@example.com/apps" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"acme-erp-integration","apiProducts":["partner-basic"]}'

5. Call it with and without the key:

HOST=your-envgroup-hostname.example.com   # from your environment group
curl -i "https://$HOST/orders-api/v1"                          # expect 401: no key
curl -i -H "x-api-key: $KEY" "https://$HOST/orders-api/v1"     # expect 200 from the mock target

6. Debug. Start a debug session on the proxy in the console, repeat the call, and open the transaction. Find the VerifyAPIKey step, read the variables it set, then find the header AM-AddAppHeader added to the target request.

Remember: the quota on the product does nothing yet. No Quota policy reads it, which is exactly the situation lesson 6 fixes.

Three use cases

1. Expose a legacy backend as a clean REST API. An internal system returns XML on awkward URLs. A proxy gives it a tidy base path, a route rule to the old URL, and mediation policies such as XMLtoJSON and AssignMessage to translate payloads and headers. Clients see a stable JSON contract; the backend team can replace the system later without a client change. Keep transformations declarative and small, and push real business rules back into the backend.

2. A partner API programme with keys and quotas. Partners register apps, receive keys, and are granted products. Two products on the same proxy (a low limit and a higher limit) create service tiers without a second proxy. VerifyAPIKey identifies the app and product, and a Quota policy reads the product's limits. Analytics then show which partner uses what.

3. A mobile backend facade (BFF). A mobile app wants one call, small payloads and a stable contract across app versions. A proxy can call several backends with a ServiceCallout policy, combine results, and trim fields, so the phone makes one round trip. Use sparingly: heavy aggregation belongs in a dedicated service, with Apigee in front for security and traffic control (see the Backend for Frontend section in API gateway and service mesh).

Apigee, a lightweight gateway or a service mesh

Apigee is an API management product: gateway plus products, apps, keys, analytics and a developer-facing lifecycle. That is more than many systems need. The comparison below is about the shape of the problem, not about specific competing products.

How to read it: the first split asks whether you manage APIs as products for consumers. A mesh is an additional layer for a different traffic direction; it does not replace the gateway, and the gateway does not replace it.

In practice: opening a legacy order system to partners

The situation

A parts distributor runs an in-house order system that returns XML. About 40 partner companies (assumed) pull order status through a reverse proxy that checks a single shared credential. Every partner uses the same secret, so one leak means rotating it for everyone. Two partners hammer the endpoint with polling loops and slow it for the rest. Nobody can say which partner generates which traffic, and the partners' IP allow-lists are maintained by hand.

Starting architecture

How to read it: identity stops at the proxy. The backend cannot tell partners apart, and there is no per-partner limit.

What changes

1. Provision and map names. Provision an organization, create a partners-prod environment, and put it in an environment group with the hostname api.partners.example.com (assumed).
2. Build orders-api. Base path /orders-api/v1, target URL the legacy system. Add VA-VerifyKey in the proxy PreFlow, an XMLtoJSON policy in the response flow, and AM-AddAppHeader so the backend logs which app called.
3. Define two products. "Partner Basic" and "Partner Plus" on the same proxy, each with its own quota values, each requiring manual approval so the partner manager vets new apps.
4. Onboard partners one by one. Each partner gets a developer record and an app with its own key. Run the old reverse proxy in parallel while partners switch, then retire the shared secret.
5. Lock the backend. Allow inbound connections to the legacy system only from the Apigee southbound path (how depends on whether you chose VPC peering or Private Service Connect), so the old route is closed rather than merely unused.

Each stage is reversible until stage 4, because the old path keeps working. Watch error rates per app in analytics before moving on.

Result

Each partner has its own credential that can be revoked without touching the others. Analytics split traffic per app, so the two heavy pollers are visible and can be moved to a lower tier or asked to back off. Product quotas, once enforced by a Quota policy, protect the legacy system from a single partner's loop. The backend team is free to modernise the system later because partners depend on the proxy's JSON contract, not on the old XML. The new costs are real: environments and proxy bundles to maintain, a pipeline to ship them, and a gateway whose availability now matters to every partner.

Architect's notes

• Design the organization on purpose. Because an organization maps to one Google Cloud project and cannot be renamed, decide early whether non-production and production share an organization (separate environments) or use separate organizations and projects. Separate organizations isolate more but multiply tooling.
• Name hostnames after audiences, not environments. Environment and group names never appear in the URL; hostnames do. A group per audience (internal, partner, public) is easier to reason about than a group per stage.
• Treat base paths as a contract. Reserve and document them. Conflicts surface at deploy time as routing conflicts, not as errors.
• Keep the gateway thin. Use built-in policies before custom code, and keep business rules in services. A slow callout is a signal the logic is in the wrong place.
• Know which choices are permanent. The hosting region and encryption key cannot be changed after provisioning, and an evaluation organization cannot be converted to a paid one.
• Plan for the gateway being critical. Every call now crosses it, so capacity, regional instances and monitoring belong in the design from the start.
• Do not forget the backend. Gateway checks do not replace backend authorisation. Treat the gateway as the first lock on the door, not the only one.

Common mistakes

• Assuming a product protects the proxy. Without a VerifyAPIKey or VerifyAccessToken step in the proxy, any caller can invoke it. Add the verification policy to the PreFlow.
• Creating a product with no proxies or environments. An unscoped product can allow every environment, and an unclear proxy list is a risk you do not need. Always list the proxies and environments.
• Expecting product quotas to enforce themselves. They are only values. Add a Quota policy that reads them, after the verification policy.
• Reading a flow variable too early. response.* does not exist in the request flow. Check the variable's scope in the reference.
• Putting the API key in the query string. URLs are logged everywhere. Use a header, and remove the key before forwarding to the backend.
• Reusing a base path across deployments. It creates a routing conflict: the deployment is not in an error state, but some of its traffic is not routed. Reserve paths.
• Putting business logic in the gateway. It couples teams to one deployable. Keep it to security, traffic and mediation.
• Treating the evaluation organization like production. It lasts 60 days, is deleted afterwards, has no SLA and is not suitable for load tests.

Key takeaways

• Apigee is a proxy layer that adds security, traffic control, mediation and analytics in front of backends without changing them.
• The control plane configures and manages; the runtime plane processes all API traffic and does not depend on a call to the control plane per request.
• An organization maps to one Google Cloud project; environments are isolated deployment spaces; environment groups own hostnames; instances are regional runtimes.
• A request runs proxy PreFlow, conditional flow and PostFlow, then the RouteRule picks a target and the target flows run; the response comes back through target then proxy flows.
• Policies communicate through flow variables, so learn the variable scope before writing conditions.
• Proxies, products, developer apps and credentials are different objects: keys are issued for products, and the proxy must verify them.
• Apigee, hybrid and Edge share concepts, but IAM, supported policies and some features differ; check the migration comparison before moving.
• Choose Apigee when APIs are products with consumers; use a lighter gateway for simple routing and a mesh only for east-west needs.

Practice exercises

Starter (about 30 min): Draw the hierarchy of an organization that has dev, test and prod environments, two environment groups (internal and partner) and one instance. Label which hostnames belong to which group, and write the full URL of a proxy with base path /orders-api/v1 for each group. Then list, in order, every flow segment a request passes through from the client to the backend.

Intermediate (about 2 h): Provision an evaluation organization with the console wizard, build the orders-api reverse proxy against https://mocktarget.apigee.net, add VA-VerifyKey and AM-AddAppHeader, create a product, developer and app with the three curl commands, and call the proxy with and without a key. In Debug, record the value of verifyapikey.VA-VerifyKey.apiproduct.name and the headers on the target request. Write two sentences explaining why the product's quota did not stop any call.

Advanced (half a day): Take a real or invented backend with three resources (/orders, /orders/{id}, /customers). Design the proxy: base path, conditional flows per resource and method, a RouteRule, and two products with different operation sets. Document the environment and hostname plan for internal and partner audiences, including what happens if the same environment joins both groups. Then write a one-page decision record choosing between Apigee, a lightweight gateway and a gateway plus mesh for this system, listing the evidence that would change your answer.

Related reading

• Course overview — the full 11-lesson roadmap and glossary.
• API Design, Products and Developer Apps in Apigee — turn proxies into products with operations, quotas and approval.
• Building Apigee API Proxies — flows, endpoints and policy attachment in depth.
• Securing APIs in Apigee — OAuth, JWT, mTLS and threat protection.
• Apigee Environments, Revisions and Deployment — promoting revisions safely across environments.
• API gateway and service mesh — the vendor-neutral view of gateways, meshes and service discovery.
• Rate limiting — the algorithms behind quotas and spike control.
• Why Apigee is the missing layer in microservices — an opinion article on why API management matters in a microservices estate.

Official documentation

• What is Apigee?
• Apigee terminology
• Understanding organizations
• About environments and environment groups
• Apigee networking options
• Understanding APIs and API proxies
• Controlling API proxies with flows
• Understanding routes
• Using flow variables
• Flow variables reference
• API proxy configuration reference
• Introduction to API products
• VerifyAPIKey policy
• AssignMessage policy
• Best practices for API proxy design and development
• What is Apigee hybrid?
• Differences between Apigee Edge and Apigee X
• Provisioning an eval org
• Build a simple API proxy