Send Docs Feedback

Configuring flows

About flows

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.

For a conceptual overview of flows, see Understanding flows.

This topic describes how to create conditional flows and add logic (policies) to flows at a high level. The art of creating conditions involves more detail than what's covered in this topic. For that detail, see Introduction to flow variables and Flow variables and conditions.

Attaching policies to flows

Edge comes with many different types of predefined policies to implement security, manage traffic, and manipulate messages. In addition, policies let you add your own custom code to completely customize message processing.

For example:

  • Attach an OAuth security policy to the request PreFlow of the ProxyEndpoint. Because the ProxyEndpoint's request PreFlow is the first flow in the pipeline, you can immediately reject a request if it violates your security policies.
  • Attach a JSON to XML conversion policy to the response PostFlow of the TargetEndpoint to convert a response from JSON to XML.
  • Attach a JavaScript policy to a Conditional Flow of the ProxyEndpoint to execute JavaScript code to process the request

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.

The following ProxyEndpoint definition shows the underlying source XML with a policy named quota-2 on the request PreFlow of the ProxyEndpoint:

<ProxyEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request>
      <Step>
        <Name>quota-2</Name>
      </Step>
    </Request>
    <Response/>
  </PreFlow>
  <Flows/> 
  <PostFlow>
    <Request/>
    <Response/>
  </PostFlow>
  ... 
</ProxyEndpoint>

About conditional flows

Any policies attached to the PreFlow or PostFlow are always executed. However, the policies in a conditional flow are executed only if the flow's condition evaluates to true.

During the processing of a request and response, only one conditional flow is executed per segment--the first flow whose condition evaluates to true. That means you can have one conditional flow executed as part of each of the:

  • ProxyEndpoint's request pipeline
  • TargetEndpoint's request pipeline
  • ProxyEndpoint's response pipeline
  • TargetEndpoint's response pipeline

For example, the following ProxyEndpoint definition shows a conditional flow that is executed by the ProxyEndpoint on any HTTP GET request to the API proxy:

<ProxyEndpoint name="default">
  <PreFlow>
    <Request/>
    <Response/>
  </PreFlow>   
  <Flows>
    <Flow name="Flow-1">
      <Condition>request.verb="GET"</Condition>
      <Request/>
      <Response/>
    </Flow>
  </Flows>
  <PostFlow>
    <Request/>
    <Response/>
  </PostFlow>
  ...
</ProxyEndpoint>

Notice that the condition references the request.verb flow variable. A flow variable is named references that hold state information associated with an API transaction processed by Edge. Edge defines many state variables that you can reference.

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 backend provides weather reports and weather forecasts, your API might define two conditional flows that map to those API resources: /reports and /forecasts. When an API call includes one of those resources in the URL, the condition evaluates to true and the logic attached to the conditional flow is executed.

App developers then access your resources by making requests to a URL in the form:

http://myAPIs.myCo.com/weather/reports

or:

http://myAPIs.myCo.com/weather/forecasts

In an API proxy, you can define a conditional flow that corresponds to a specific resource:

<ProxyEndpoint name="default">
  <PreFlow>
    <Request/>
    <Response/>
  </PreFlow>   
  <Flows>
    <Flow name="Flow-1">
      <Condition>(proxy.pathsuffix MatchesPath &quot;/reports&quot;)</Condition>
      <Request/>
      <Response/>
    </Flow>
    <Flow name="Flow-2">
      <Condition>(proxy.pathsuffix MatchesPath &quot;/forecasts&quot;)</Condition>
      <Request/>
      <Response/>
    </Flow>
  </Flows>
  <PostFlow>
    <Request/>
    <Response/>
  </PostFlow>
  ...
</ProxyEndpoint>

In this example, you reference the proxy.pathsuffix flow variable, which contains the suffix portion of the URL used to access the API proxy. You can then attach different policies to the conditional flow for each resource.

Adding a conditional flow

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 default.

Select the Proxy endpoint default option.

The new flow, called Flow-1, now appears 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>

Next steps

The following topics provide more detail about constructing conditions and using variables:

Help or comments?