Reusable shared flows

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

You can combine policies and resources into a shared flow that you can consume from multiple API proxies, and even from other shared flows. Although it's like a proxy, a shared flow has no endpoint. It can be used only from an API proxy or shared flow that's in the same organization as the shared flow itself.

By capturing in one place functionality that's useful in multiple places, a shared flow helps you ensure consistency, shorten development time, and more easily manage code.

The following video demonstrates how to create and trace a shared flow in the Edge UI.

The following 5-minute video demonstrates how to create and trace a shared flow in the Classic Edge UI (Edge for Private Cloud only).

You can call a shared flow using the FlowCallout policy. Also, by attaching a shared flow to a flow hook, you can have the shared flow execute before a proxy or target request, or after a proxy or target response.

For reference on the FlowCallout policy, see FlowCallout policy. For more on flow hooks, see Attaching a shared flow using a flow hook.

For example, imagine you have areas of functionality that are either used in multiple places or must be standardized across APIs in your organization. You could have a shared flow for each category, including:

security, with authorization code using OAuth and API key verification, as well as threat protection code.
logging, for generating standard error messages.
mediation, for transforming between XML and JSON message formats.

In the following illustration, two API proxies call out (with a FlowCallout policy) to a shared flow to authenticate incoming user requests. The AuthSharedFlow has been deployed separately to the org before the proxies so that it is available to support requests from the proxies. A shared flow can be developed and managed by a team responsible for broad company policies, then consumed in proxies by line-of-business teams building more specialized apps.

Developing a shared flow

When developing a shared flow, you must always test it with calls sent to an API proxy. In other words, you can't send requests directly to a shared flow as you would an API proxy. Instead, you send requests to an API proxy which is, in turn, calling out to the shared flow.

Here are the high-level steps for developing a shared flow:

Figure out what the shared set of features should be.
For example, you might want to combine traffic management features, including suppressing traffic spikes. That way, you can manage their configuration outside the workflow of those implementing line-of-business logic.
Develop a shared flow by implementing policies and supporting resources, just as you would when developing an API proxy.
A shared flow is a sequence of conditional steps. So developing one is like developing an API proxy. You can include policies and resources you might include in a proxy.

For example, as part of your traffic management support, you might implement a Spike Arrest policy to allow only 30 requests per second, as in the following example:
```
<SpikeArrest async="false" continueOnError="false" enabled="true" name="Spike-Arrest">
    <DisplayName>Spike Arrest</DisplayName>
    <Properties/>
    <Identifier ref="request.header.some-header-name"/>
    <MessageWeight ref="request.header.weight"/>
    <Rate>30ps</Rate>
</SpikeArrest>
```
Then, to a shared flow for traffic management, you could attach the Spike Arrest policy as a step. The policy would execute for any API proxy that calls the shared flow.
```
<SharedFlow name="default">
    <Step>
        <Name>Spike-Arrest</Name>
    </Step>
</SharedFlow>
```
For information on how to get a shared flow started in the management console, see Creating a shared flow in the Edge UI.

As with API proxies, you can import a zip file containing your shared flow source artifacts (see Import a new API Proxy for more about importing proxies). The following illustrates how to import a shared flow with the management API:
```
curl -X POST -F "file=@/path/to/zip/file.zip" \ 'https://api.enterprise.apigee.com/v1/o/{org_name}/sharedflows?action=import&name=shared-flow-name' \
-u email:password
```
Deploy the shared flow to the environment before deploying proxies or shared flows that will consume it. You deploy a shared flow in the same way you deploy an API proxy. (For more, see Deployment overview.)
A shared flow must be in the same org and deployed to the same environment as the API proxies and other shared flows that consume it. Deploying the shared flow before the proxies makes it possible to resolve the proxy's dependency on the shared flow at deploy time.

You can deploy a shared flow with a management API call such as the following:
```
curl -X POST --header "Content-Type: application/octet-stream" \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/sharedflows/{shared_flow_name}/revisions/{revision_number}/deployments \
-u email:password
```
You can also replace a currently deployed shared flow with no downtime. (This is very like API proxies. See Deploy API proxies using the management API for more). Here's the request form using the management API:
```
curl -X POST --header "Content-Type:application/x-www-form-urlencoded" \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/sharedflows/{shared_flow_name}/revisions/{revision_number}/deployments?"override=true" \
-u email:password
```
Develop the consuming API proxy so that it can call the shared flow as part of its own flow.
From an API proxy, you call to a shared flow with a FlowCallout policy. (You can also attach the shared flow to the proxy using a flow hook, as described in Attaching a shared flow using a flow hook.) For an introductory tutorial on creating an API proxy, see Build your first API proxy.

To consume a shared flow, you add a FlowCallout policy to the proxy or shared flow that will consume it. Like a Service Callout policy, with which you call out to another service, a FlowCallout calls out to the shared flow. The consuming API proxy must be deployed after the shared flow and to the same environment as the shared flow. The shared flow has to be in place when you want to test a call to it using the FlowCallout policy.

In the following code, a FlowCallout policy calls out to a shared flow called traffic-management-shared.
```
<FlowCallout async="false" continueOnError="false" enabled="true" name="Traffic-Management-Flow-Callout">
    <DisplayName>Traffic Management FlowCallout</DisplayName>
    <Properties/>
    <SharedFlowBundle>traffic-management-shared</SharedFlowBundle>
</FlowCallout>
```
For more, see Calling a shared flow from an API proxy or shared flow
Deploy the consuming API proxy to begin using the shared flow. (For more on deployment in general, see Understanding deployment.)
Develop iteratively by tracing, as you would with an API proxy.
As with an API proxy, you develop a shared flow by iteratively invoking and tracing until you have the logic the way you want it. In this case, because the shared flow doesn't run on its own, you invoke a proxy endpoint and trace the proxy.

Here are the steps:
1. Make sure that both the shared flow and the API proxy calling it with a FlowCallout policy are in the same organization and deployed to the same environment.
2. On the API proxy's Trace tab, begin tracing the API proxy.
3. Send a request to a proxy endpoint in the API proxy. The flow from the endpoint must include the FlowCallout policy that calls out to the shared flow.
4. On the Trace tab, examine the flow from the API proxy to the shared flow.
  Notice that in tracing, the shared flow is represented as a set of steps or policies enclosed in a grey box. Icons representing FlowCallout policies precede shared flows. (For more on tracing, see Using the Trace tool.)

Creating a shared flow in the Edge UI

When you use the Apigee Edge UI to create a shared flow, you can either create one from scratch or by importing existing flow sources as a flow bundle .zip file.

Access the Shared Flows page, as described below. On the Shared Flows page, you can view a list of shared flows in the organization, and edit or delete flows in the list.
Edge

To access the Shared Flows page using the Edge UI:
1. Sign in to apigee.com/edge.
2. Select the organization containing your shared flow. See Switching between your organizations.
  The shared flow will be available to any API proxies and shared flows deployed to an environment from this organization. It won't be available from outside this organization.
3. Select Develop > Shared Flows in the left navigation bar.
Classic Edge (Private Cloud)

Note: The Classic Edge UI is available with Edge for Private Cloud only.

To access the Shared Flows page using the Classic Edge UI:
1. Sign in to http://ms-ip:9000, where ms-ip is the IP address or DNS name of the Management Server node.
2. Select the organization containing your shared flow. See Switching between your organizations.
  The shared flow will be available to any API proxies and shared flows deployed to an environment from this organization. It won't be available from outside this organization.
3. Select APIs > Shared Flows in the top navigation bar.
Click the + Shared Flow button to begin adding a new shared flow.
On the Build a Shared Flow page, choose how you want to create the new flow:
- Create a new flow from scratch. You'll be able to configure policies and resources as steps in the flow.
  1. Select Empty Shared Flow.
  2. Enter a name value. This will be the name that API proxies and other shared flows use to reference this shared flow. The name should be descriptive to developers consuming the flow.
  3. Enter a description to provide more information about what the flow does.
  4. Click Next.
  5. Optionally, select the environments to which you want the new flow deployed.
    For example, if you'll be testing the shared flow from API proxies deployed to the test environment, then deploy the shared flow to test.
  6. Click Build and Deploy to have the new shared flow created and deployed to the environment(s) you selected. If you selected no environment, the shared flow will be created, but not deployed.
- Create a shared flow from existing sources by uploading a flow bundle.
  1. Select Shared Flow Bundle to specify a .zip file containing the artifacts you want in the new flow.
    A shared flow bundle contains the source artifacts of a shared flow. For example, if you were to download a shared flow from the Edge UI, you'd have a .zip file with the flow bundle.
  2. Click Next.
  3. Click Choose File to browse for the .zip file containing the shared flow sources you want to import.
  4. In the Shared Flow Name box, enter a name for the imported flow. This will be the name that API proxies and other shared flows use to reference this shared flow. The name should be descriptive to developers consuming the flow.
  5. Click Next.
  6. Click Build to build the new flow from the sources you're importing.

Calling a shared flow from an API proxy or shared flow

You can call a shared flow from a proxy or from another shared flow by using the FlowCallout policy.

In the Edge UI, locate the proxy or shared flow from which you want to call another shared flow.
In the Navigator, next to Policies, click the + button.
In the list of policies, under Extension, click FlowCallout.
Enter the display name and name (unique identifier), then select the shared flow that this policy will call.
Click Add.
Add the new FlowCallout policy to the proxy where you want the call to be made.

Reusable shared flows

Developing a shared flow

Creating a shared flow in the Edge UI

Edge

Classic Edge (Private Cloud)

Calling a shared flow from an API proxy or shared flow

See also