Attaching and configuring policies in the UI

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

Adding policy-based capabilities to an API proxy is a two-step process:

1. Configure an instance of a policy type.
2. Attach the policy instance to a Flow.

The diagram below shows the relationship between policies and flows. As you can see, a policy is attached to a flow as a processing step. To configure the desired behavior for your API, you need to understand a little bit about flows. (This topic was covered earlier in Configuring flows.)

One type of policy that is commonly used is the SpikeArrest policy. SpikeArrest prevents sudden increases in message traffic that might swamp your backend services.

Attaching a policy to a flow

Note: Apigee is introducing a new version of the Proxy Editor, which will make it easier to manage proxies.

The instructions in the first two tabs below explain how to use either the new Proxy Editor or the classic Proxy Editor.

New Proxy Editor

To attach a policy to a flow:

1. Select an API proxy and navigate to the Develop view.
2. In the left-hand pane, click the + button in the Policies row.

3. In the Create policy dialog, click in the Select policy type field and scroll down to Traffic Management and select SpikeArrest.

4. Optionally, you can change the Display name and Name of the policy.

   

   When you are done, click Create to create the policy.

5. Now that you have created the Spike Arrest policy, you can attach it to a step in the PreFlow. To do so, select Proxy Endpoints > default > PreFlow in the left-hand pane:

   

6. Click the + button next to PreFlow in the Response pane at the bottom-right of the Visual Editor:

   

7. In the Add policy step dialog, select the Spike Arrest policy.

8. Click Add to attach the policy.

   The Spike Arrest policy is now displayed in the Response pane:

   

   The following XML code for the proxy is displayed in the text editor:

   <ProxyEndpoint name="default">
     <PreFlow name="PreFlow">
       <Request/>
       <Response>
         <Step><
           <Name>SA-</Name>
         </Step>
       </Response>
     </PreFlow>
     <Flows/>
     <PostFlow name="PostFlow">
       <Request/>
       <Response/>
     </PostFlow>
     <HTTPProxyConnection>
       <BasePath>/myproxy</BasePath>
     </HTTPProxyConnection>
     <RouteRule name="default">
       <TargetEndpoint>default</TargetEndpoint>
     </RouteRule>
   </ProxyEndpoint>
     

Detaching policies from a flow

To detach a policy from a flow, click the three-dot menu next to the flow and select Delete policy step

Classic Proxy Editor

To attach a policy to a flow:

1. Select an API proxy and navigate to the Develop view.
2. In the API Proxy Editor, select the flow to which you want to attach a policy in the Navigator pane.
   For example, the PreFlow flow is selected for the default API proxy endpoint in the following figure:
   
3. In the Design view, click +Step associated with the request or response flow to attach a policy. For example:
   
   The Add Step dialog opens displaying a categorized list of policies.
   
4. Scroll and select the policy type that you want to attach to the selected flow.
5. Modify the following fields.

   • Display Name: Unique display name for the policy. The UI will generate a default name, but it is advisable to create a descriptive name for the policy. This will ensure that other developers in your organization have an easy time understanding what the policy is intended to do.

   • Name: Unique name for the policy. The policy name matches the display name with the following exceptions:

     • Spaces are replaced by dashes.

     • Consecutive dashes are replaced by a single dash.

     • Except for dashes, underscores, and spaces (which are replaced, as noted above), characters that are not alphanumeric, such as pound signs, percent signs, ampersands, and so on, are removed.

6. Click Add.

   The policy is attached to the selected flow.

After the policy is attached, you’ll see the policy displayed in the Designer view for the flow, in this example the PreFlow of the default proxy endpoint, and in the Policies list in the Navigation pane. The Code view, which displays the XML for the newly attached policy, displays below the Designer view. Apigee generates an instance of the policy that contains a set of reasonable default values.

Adding a policy without attaching it to a flow

To add a policy without attaching it to a flow, which is useful for Handling faults, click + in the Policies bar in the Navigator view to open the Add Policy dialog and add the policy (as described in steps 4 through 6 in the previous section).

A policy that is not attached to any flow is flagged with the detached icon in the Policies list, as shown adjacent to the API key message policy shown in the previous figure.

After you create the policy, you can attach it to a flow by dragging and dropping it from the Policies list to the desired flow in the Designer view.

Detaching policies from a flow

To detach a policy from a Flow, select the Flow. Mouse over the icon for the policy in the Designer view of the Flow. Click the X in the circle that appears in the icon.

Deleting a policy instance

To delete a policy instance, mouse over the entry for the policy in the Navigator view. Click the X in the circle that appears to the right of the entry.

Configuring policies in the UI

When the UI generates a policy instance, it applies reasonable default values for common settings. You may need to modify these settings to meet your requirements.

For example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SpikeArrest async="false" continueOnError="false" enabled="true" name="spikearrest-1">
  <DisplayName>SpikeArrest-1</DisplayName>
  <FaultRules/>
  <Properties/>
  <Identifier ref="request.header.some-header-name"/>
  <MessageWeight ref="request.header.weight"/>
  <Rate>30ps</Rate>
</SpikeArrest>

You can configure a policy by directly editing its XML configuration in the Code view. For example, the peak message rate for the Spike Arrest policy is initially set to 30 messages per second. You can change the peak rate by changing the <Rate> element value in the XML for the policy. For further details about configuring policies, see the Policy reference.

You can also cut-and-paste policies into the Code view. This is a great way to re-use policies from the samples available on GitHub.

When you make changes to a policy definition in the Code view, the changes are reflected in the Property Inspector. The reverse is also true — make changes in the Property Inspector and they appear in the XML in the Code view.

For documentation specific to the Quota policy used in this topic, see Quota policy.

Use Gemini Code Assist code explain with policies

Preview — Gemini Code Assist policy code explain

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

If you have Gemini Code Assist, you can use it to understand policies and policy elements directly in the Apigee UI in Cloud console:

• While editing the policy in the Code view, highlight part of the policy code, such as an XML element or attribute. You can also highlight multiple elements.
• Click the Gemini Code Assist icon as shown below. The side panel shows information on the policy and the element you highlighted.
  Alert: Clicking the Gemini Code Assist icon sends the highlighted text to Gemini in Google Cloud console.