Introduction
Share Flows support DRY (Don’t Repeat Yourself) by providing a reusable sequence of policies, the Shared Flow, that can be used by API proxies, either through a FlowCallout policy or configured as a Flow Hook.
Flow Hooks are merely a way to “hook” an existing Shared Flow to a particular “flow” (Pre or Post flows in Proxy or Target) across all proxies in an environment, without having to add it to the consuming API proxy.
It is important to note that the shared flow and policies can change independent of the API proxy that is using it.
There is no Shared Fault Flow. The Shared Flow executes within the consuming API proxy flow, therefore all faults must be managed in the consuming API proxy Fault Rules. But guess what, you can put Flow Callouts to Shared Flows there and finally be able to provide consistent and consolidated fault handling for all your API proxies!
Beyond reuse and consistency, API design simplification is a huge benefit, since a single Flow Callout can execute multiple policies in a Shared Flow.
The examples below are just a start, what other reuse cases do you have?
Objectives
- to define reusable flows of policies that can be used by API proxies within an environment.
- to contrast when to configure a Shared Flow as a Flow Hook.
Overview
Shared Flows allow the API team to focus on the core aspects of the API, the gist of the API. The new API can then be augmented with Shared Flows or simply take advantage of a deployed Flow Hook.
Typical use cases for Shared Flows are:
- API security - ensure API Key is handled consistently
- Logging - common logging
- Fault Handling - finally a way to consistently handle faults across all proxies!
Typical use cases for Flow Hooks are:
- CORS - Add CORS with no effort to API developers
Alternatives to Shared Flows
- Build time inclusion of common policies from source code repository
- API proxy templates or design patterns provided in source code repository that developers use to jump start a similar design (e.g. Node.js based proxy to database).
- Proxy Chaining
Examples
Verify API Key in Shared Callout
This example shows a Shared Flow to ensure consistency on the use of and API key across all proxies. The flow executes 2 policies a Validate API Key using X-APIKey header and an Assign Message to remove sensitive header information, a step often overlooked.
The Shared Flow named ValidateAPIKey
The shared flow
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SharedFlow name="default">
<Step>
<Name>Verify-API-Key</Name>
</Step>
<Step>
<Name>AM-Remove-Sensitive-Headers</Name>
</Step>
</SharedFlow>
The Verify API Key policy
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VerifyAPIKey async="false" continueOnError="true" enabled="true" name="Verify-API-Key">
<DisplayName>Verify API Key</DisplayName>
<Properties/>
<APIKey ref="request.header.X-APIKey"/>
</VerifyAPIKey>
The Assign Message policy
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssignMessage async="false" continueOnError="false" enabled="true" name="AM-Remove-Sensitive-Headers">
<DisplayName>AM - Remove Sensitive Headers</DisplayName>
<Properties/>
<Remove>
<Headers>
<Header name="x-apikey"/>
</Headers>
</Remove>
<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
<AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>
Using the Flow Callout Policy
Use in the Proxy PreFlow
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ProxyEndpoint name="default">
<Description/>
<FaultRules/>
<PreFlow name="PreFlow">
<Request>
<Step>
<Name>FC-ValidateAPIKey</Name>
</Step>
</Request>
<Response/>
</PreFlow>
...
The FlowCallout policy
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<FlowCallout async="false" continueOnError="false" enabled="true" name="FC-ValidateAPIKey">
<DisplayName>FC - ValidateAPIKey</DisplayName>
<FaultRules/>
<Properties/>
<SharedFlowBundle>ValidateAPIKey</SharedFlowBundle>
</FlowCallout>
Fault Handling with Flow Callouts
This example shows how you can use Shared Flows in Fault Rules
<ProxyEndpoint name="default">
<Description/>
<DefaultFaultRule name="DefaultFaultRule">
<Step>
<FaultRules/>
<Name>FC-DefaultFaultRule</Name>
</Step>
<AlwaysEnforce>true</AlwaysEnforce>
</DefaultFaultRule>
<FaultRules>
<FaultRule name="FaultRules">
<Step>
<!-- Put all your Fault Rules in one Shared Flow -->
<Name>FC-FaultRules</Name>
</Step>
</FaultRule>
</FaultRules>
The Shared Flow for FaultRules
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SharedFlow name="default">
<Step>
<Condition>fault.name = "FailedToResolveAPIKey" or fault.name = "InvalidApiKey"</Condition>
<Name>AM-Fault-API-Key</Name>
</Step>
</SharedFlow>
CORS in Flow Hook
This example shows how to configure Flow Hooks to support CORS. Recall that to fully support CORS, the pre-flight OPTIONS request must be processed in the Proxy PreFlow and CORS headers added in the Proxy PostFlow
The Shared Flow in the CORSPreFlow bundle
<SharedFlow name="default">
<Step>
<Condition>(request.verb = "OPTIONS")</Condition>
<Name>JS-Extract-CORS-Headers</Name>
</Step>
<Step>
<Condition>(request.verb = "OPTIONS")</Condition>
<Name>RF-CORS-Pre-Flight</Name>
</Step>
</SharedFlow>
The Shared Flow in the CORSPostFlow bundle
<SharedFlow name="default">
<Step>
<Name>AM-Add-CORS-Headers</Name>
</Step>
</SharedFlow>
The configuration of the Flow Hooks
Useful links
http://apigee.com/docs/enterprise/content/shared-flows
http://apigee.com/docs/enterprise/content/flow-hooks