Send Docs Feedback

Part 2: Add policies to your API

About policies

To customize the behavior of your APIs, you apply a set of policies. Policies are processing steps that run on Apigee Edge, not on your backend services, and enable you to augment your API without requiring you to write any code or to modify any backend services. Use policies to:

  • Control traffic
  • Enhance performance
  • Enforce security
  • Increase the utility of your APIs

Extension policies enable you to implement custom logic in the form of JavaScript, Python, Java, and XSLT.

If you add multiple policies to an API proxy, you can control the order in which the policies are executed. For example, if you add a security policy to an API proxy that denies access to anyone without valid credentials, you can specify that the security policy execute first, before any other policies execute.

When you add a policy, you add it to a specific Flow that defines when the policy is executed. Each request and response path in a ProxyEndpoint and TargetEndpoint defines the following Flows:

  • PreFlow: Always executes before any other Flows. The policies defined in the PreFlow are applied to every message that passes through an Endpoint. 
  • Conditional Flows:  Execute only when a conditional statement defined for the Flow evaluates to true. An endpoint can define any number of conditional Flows, but only the first conditional Flow whose condition evaluates to true executes. That means the policies attached to the conditional Flow only execute when the conditional Flow executes. 
  • PostFlow: Always executes after all other Flows. As with PreFlow, the policies defined in the PostFlow are applied to every message.

Learn about flows and endpoints in Understanding APIs and API proxies.

Prerequisites for this tutorial

This tutorial assumes that you have completed the first tutorial, where you create an API proxy to access the Yahoo weather API. If you have not yet completed that tutorial, see Part 1: Create your API.

Step 1: Add a Spike Arrest policy to set a rate limit for your API

The Spike Arrest policy prevents traffic spikes (or bursts) that can be caused by an increase in usage, buggy clients, or malicious attacks. When the number of requests exceeds the rate limit, the API returns an HTTP 500 error for a request. Because the Spike Arrest policy is implemented by the API proxy on Edge, your backend is shielded from handling any request that exceed the rate limit.

Add the Spike Arrest policy to an API proxy:

  1. In the main menu of the management UI, click APIs to display the API Proxies page. If the API Platform page is not open, click here.
  2. Click weather in the API Proxies table. This is the API proxy that you created in the tutorial Part 1: Create your API.
  3. On the upper-right side of the weather detail page, click the Develop tab to open the API Proxy Editor.

    The API Proxy Editor lets you see the structure of your API proxy and configure its flow. The editor presents a visual representation of your proxy's message flows as well as an editable display of the XML that defines the proxy.

  4. In the API Proxy Editor, click PreFlow under Proxy Endpoints to add the policy to that flow.

    Note that you could have added the policy to the forecast conditional Flow as well. If so, the policy would execute only when the forecast conditional Flow executes. In this example, you want the policy to execute on every request, and before any other policies, so you put it in the PreFlow.
  5. Click the top +Step button, corresponding to the Request PreFlow. This displays a categorized list of all the policies you can create.
  6. Select Spike Arrest in the Traffic Management category. The New Policy dialog appears:
    • Leave the Display Name field with the default display name of the new policy, Spike Arrest 1.
    • Leave the Name field with the default name of the new policy, Spike-Arrest-1.
  7. Click Add. The new policy is attached to the PreFlow flow of a request.
  8. Ensure that PreFlow under Proxy Endpoints is still selected in the left side of the API Proxy Editor.
  9. Select Spike Arrest 1 under policies and examine what’s been added to the API Proxy Editor:
    • The policy is added to the list of policies in the Navigator view in the upper left of the API Proxy Editor.
    • The policy is added to the Designer view in the top center of the API Proxy Editor, which is a visual representation of your proxy's message flows. Note that the icon appears only when you select PreFlow under Proxy Endpoints in the left navigation area.
    • The XML for the policy is displayed in the Code view in the bottom center of the API Proxy Editor.
    • The XML element and attribute values for the policy are displayed in the Property Inspector at the right in the API Proxy Editor.
  10. In the XML for the policy, change the value of the <Rate> element to 1pm. You can specify the rate as an integer value per minute (pm) or per second (ps). This is a very low limit and is used only for this tutorial to demonstrate the policy. Typically, you set it to a much higher limit.
    Notice that the Rate value in the Property Inspector also changes to 1pm. You can change the Rate value in the Property Inspector and it will be reflected in the XML view.
  11. Click Save to save the current revision with your changes.
  12. Make a request to the API in your Web browser by entering the following, substituting your Apigee organization name for {org-name}:
    For example:
    Make sure the request succeeds and you see weather information.
  13. Refresh the browser within one minute, and notice that on the refresh, you get the following message in the browser because you exceeded the rate limit of the policy:

    {"fault":{"faultstring":"Spike arrest violation. Allowed rate : 1pm","detail":{"errorcode":"policies.ratelimit.SpikeArrestViolation"}}}
  14. Edit your policy to set the rate limit to 10pm, and then save the policy. You can now make one request every six seconds, or 10 requests per minute, before you exceed the rate limit.
  15. Refresh the browser until you cause a rate limit violation.

Learn more

Spike Arrest policy

Step 2: Add a policy to convert XML to JSON

The response from your weather API contains XML data. This can be a problem for developers whose apps want to access the backend service through your API, but only accept JSON responses. To solve this issue, add the XML to JSON policy to your API to convert response data from XML to JSON. Because the policy executes on Edge, you can perform the data conversion without modifying your backend service.

With this policy, the payload of an XML response is parsed and converted into JSON, and the Content-type header is changed to application/json. The policy only works when the source Content-type header is application/xml.

Add an XML to JSON policy:

  1. In the management UI, click the APIs tab. If the API Platform page is not open, click here.
  2. Click weather in the API Proxies table.
  3. On the weather detail page, click the Develop tab to open the API Proxy Editor.
  4. In the API Proxy Editor, click PostFlow under Proxy Endpoints to add the policy to that flow.
  5. Click the bottom +Step button, corresponding to the Response PostFlow. This displays a categorized list of all the policies you can create.
  6. Select XML to JSON in the Mediation category.
  7. In the New Policy dialog select the following keep the default values for Display Name and Name.
  8. Click Add. The XML to JSON policy is applied to the PostFlow flow of the response.
    If the XML to JSON policy does not appear under Response in the Designer area of the screen, select PostFlow under Proxy Endpoints in the left navigation area. To see the Spike Arrest policy, select PreFlow under Proxy Endpoints.
  9. Click Save.
  10. Request the URL of the API in a browser to see that the response is now formatted as JSON:

Learn more

Step 3: Where to next?

Now that you have a working API with policies, you can find out more about how to use Edge development tools. The Edge Trace tool helps you to troubleshoot and monitor API proxies running on Apigee Edge. Trace lets you probe the details of each step through an API proxy flow, view the request and response objects, view response times, and more.

Continue on to Part 3: Trace API calls to use the Trace tool.

Help or comments?