Flows are the basic building blocks of API proxies. Flows enable you to program the behavior of an API by letting you configure the sequence in which policies and code are executed by an API proxy.
As shown in the diagram below, API proxies define request and response Flows. The request and response Flows are subdivided into proxy and target segments. Each segment is subdivided into 3 Flow 'stages':
- PreFlow: Always executes before any conditional Flows.
- Conditional Flows: One or more Flows, each of which has an associated Condition. Only one Flow executes per transaction--the first Flow whose Condition evaluates to true.
- PostFlow: Always executes after any conditional Flows.
- PostClientFlow: An optional Flow that executes after the response message has been sent to the requesting client app. (This is a specialized Flow, and only MessageLogging policies can be attached to it.)
This may look complicated, but it's fairly simple once you understand a few use cases.
PreFlows are useful when you need to make sure that a policy or code executes before anything else happens. For example, you usually don't want an API proxy to waste any resources on an unauthenticated user. Also, you don't want to service an app that has exceeded its quota. To support these requirements, you put security and quota policies in the PreFlow segment. That way, you don't need to worry about a condition failing to evaluate. The policies will always execute before any other processing takes place.
PostFlow is useful when you need to log some data or send a notification that something happened. Like PreFlow, the PostFlow always executes, regardless of the situation.
API proxy programming starts to get interesting when you implement 'branching' logic for an API. For example, you might want to convert XML to JSON only when the requesting app is running on a mobile device. You might want to return a targeted ad based on the data in the user's request. You can do this by setting up conditional Flows.
In this brief example, you set up a Flow that executes only when the request message is an HTTP GET.
To add a conditional Flow, select the Develop view in the API proxy builder. Select New > Conditional Flow.
The New Conditional Flow form enables you name the Flow and to add a condition. In this example, you add a condition that evaluates the HTTP of the request message. You add a condition that will evaluate to true if the HTTP verb is GET (as opposed to PUT, POST, etc.)
(Learn how to construct conditional statements in Flow variables and conditions.)
The form also enables you to add the Flow to the ProxyEndpoint named
default or the TargetEndpoint named
Select the Proxy endpoint default option.
The new Flow, called
Flow-1, now displays in the Navigator menu.
Now observe the XML configuration for the ProxyEndpoint. Select Flow-1 in the Navigator menu.
You will see the following configuration.
<PreFlow name="PreFlow"> <Request/> <Response/> </PreFlow> <Flows> <Flow name="Flow-1"> <Request/> <Response/> <Condition>request.verb="GET"</Condition> </Flow> </Flows> <PostFlow name="PostFlow"> <Request/> <Response/> </PostFlow>
Once you have created a conditional Flow, it is available for Policy attachment. When you select New > Policy after you create the Flow, you will see an additional option in the list of Flows. As shown below, when adding a Quota policy, you now have the option to attach the Policy to the Flow called Flow-1, which you just created.
By attaching the Policy to Flow-1, you are configuring the API proxy to enforce the Quota Policy only for requests submitted using the GET verb. The Quota will not be enforced for POSTs, PUTs, etc.
In the next topic, you will see how conditional Flows enable you to configure fine-grained management for RESTful APIs by creating a conditional Flow for each URI that represents a RESTful resource defined by your API.