Mapping conditional flows to backend API resources

Understanding API resources and conditional flows

Check out this short video for an introduction to the relationship between your RESTful backend resources and Edge proxy resources, or conditional flows.


RESTful services are collections of API resources. An API resource is a URI path fragment that identifies some entity that developers can access by calling your API. For example, if your service provides weather reports and weather forecasts, your backend service might define two API resources:


When you create an API proxy (as shown in the Get Started with Apigee Edge tutorial), at a minimum you're creating an alias base URL that maps to your backend service. For example:

Backend base URL New/equivalant API proxy URL http://{your_org}-{environment}

At this point you can make API calls to your backend using either base URL. But when you use the API proxy URL, things start to get interesting.

In addition to API analytics that Edge starts to collect when you use the API proxy, proxies also let you define conditional flows that map to the resources on your backend. In essence, "If a GET call comes in to the /reports resource, Edge should do something."

The following image shows the behavior difference between two URLs that ultimately access the same backend. One is the un-proxied resource URL, the other is an Edge API proxy with a conditional flow to the same backend resource. We'll describe conditional flows in more detail below.

How API proxies map to specific backend resources

With an API proxy URL mapped to the base URL of the backend service (when you create the proxy), you can add conditional flows to specific resources, such as the /reports and /forecasts resources mentioned earlier.

Let's say you wanted to have Edge "do something" when calls come in to the /reports or /forecasts resources. At this point you're not telling Edge what to do, just that it should be listening for calls to those resources. You do this with conditions. In your Edge API proxy, you can create conditional flows for /reports and /forecasts. For conceptual purposes, the following API proxy XML shows what those conditions might look like.

    <Flow name="reports">
        <Condition>(proxy.pathsuffix MatchesPath "/reports") and (request.verb = "GET")</Condition>
    <Flow name="forecasts">
        <Condition>(proxy.pathsuffix MatchesPath "/forecasts") and (request.verb = "GET")</Condition>

Those conditions say, "When a GET request comes in with /reports and /forecasts in the URL, Edge will do whatever you (the API developer) tell it to, through the policies you attach to those flows.

Now here's an example of telling Edge what to do when a condition is met. In the following API proxy XML, when a GET request is sent to, Edge executes the "XML-to-JSON-1" policy in the response.

    <Flow name="reports">
        <Condition>(proxy.pathsuffix MatchesPath "/reports") and (request.verb = "GET")</Condition>

Note about default flows

In addition to those optional conditional flows, each API proxy also comes with two default flows: a <PreFlow> executed before your conditional flows, and a <PostFlow> executed after your conditional flows. Those are useful for executing policies when any call is made to an API proxy. For example, if you want to verify an app's API key with every call, regardless of the backend resource being accessed, you could put a Verify API Key policy on the <PreFlow>. For more on flows, see Configuring flows.

Creating conditional flows to backend resources

Defining conditional flows to backend resources in an API proxy is completely optional. However, those conditional flows give you the ability to apply fine-grained management and monitoring.

You will be able to:

  • Apply management in way that reflects the semantics of your API model
  • Apply policies and scripted behavior to individual resource paths (URIs)
  • Collect fine-grained metrics for Analytics Services

For example, imagine that you need to apply different types of logic to your backend /developers to /apps resources.

To do so, you add two conditional flows in your API proxy: /developers and /apps.

In the Develop view of the API proxy editor Navigator pane, click the + icon next to default in the Proxy Endpoints.

In the "New Conditional Flow" window, you'd enter the following key configurations:

  • Flow name: Developers
  • Condition Type: Path
  • Path: /developers

The condition will be triggered (and policies will be executed) if a call is sent to the proxy with /developers at the end of the URI.

Now add a conditional flow for /apps, and assume you want the condition to be triggered on both the URI and the POST verb in a request. The configuration involves setting the following:

  • Flow Name: Apps
  • Condition Type: Path and Verb
  • Path: /apps
  • Verb: POST

The condition will be triggered (and policies will be executed) if a call is sent to the proxy with /apps at the end of the URI and a POST verb.

In the Navigator pane, you'll see new flows for Apps and Developers.

Select one of the flows to view the conditional flow configuration in the API proxy editor code view:

<Flow name="Apps">
    <Description>Developer apps registered in Developer Services</Description>
    <Condition>(proxy.pathsuffix MatchesPath "/apps") and (request.verb = "POST")</Condition>

As you can see, API resources are simply conditional Flows that evaluate the URI path of the inbound request. (The proxy.pathsuffix variable identifies the URI of the request that follows the BasePath configured in the ProxyEndpoint configuration.)

Each API resource that you define is implemented by a conditional Flow in the API proxy. (See Configuring flows.)

Once you deploy the API proxy to the test environment, the following request:


will cause the condition to evaluate to true, and this flow, along with any associated policies, will execute.

Building conditions

For more information on building conditions, see the Conditions reference. For example, the following condition uses a Java regular expression to recognize calls made to the /apps resource with or without a trailing forward slash (/apps or /apps/**):

<Condition>(proxy.pathsuffix JavaRegex "/apps(/?)") and (request.verb = "POST")</Condition>

For more about this type of condition, see the follwing Apigee Community thread:

Modeling hierarchical URIs

In some cases, you will have hierarchical API resources. For example, the Developer Services API provides a method for listing all apps that belong to a developer. The URI path is:


You may have resources where a unique ID is generated for each entity in a collection, which is sometimes annotated as follows:


This path applies equally to the following two URIs:


To represent this structure in an API resource, you can use wildcards. For example:


will resolve these hierarchical URIs as API resources appropriately.

In some cases, especially for deeply hierarchical APIs, you may simply want to resolve everything below a certain URI fragment. To do so, use a double asterisk wildcard in your resource defintiion. For example, if you define the following API resource:

That API resource will resolve the following URI paths:


Here's what the conditional flow condition would look like in the API proxy definition:

<Condition>(proxy.pathsuffix MatchesPath "/developers/**") and (request.verb = "POST")</Condition>
Was this page helpful? Let us know how we did:

Send feedback about...

Apigee Docs