—Rate this article—
 

Part 2: Add policies to your API

About policies

To customize the behavior of your APIs, you apply a set of policies. Policies 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 want to 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 want that policy to execute first, before any other policies execute.

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

  • PreFlow: Always executes before any other Flows. The processing steps 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 may define any number of conditional Flows, but only the first conditional Flow whose condition evaluates to true will execute. 
  • PostFlow: Always executes after all other Flows. As with PreFlow, the processing defined for PostFlow is 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 New Policy button. This displays a categorized list of all the policies you can create.
  5. Select Spike Arrest in the Traffic Management category. The New Policy dialog appears:
    • Leave the Policy Display Name field with the default display name of the new policy, Spike Arrest 1.
    • Leave the Policy Name field with the default name of the new policy, Spike-Arrest-1.
    • Make sure that the Attach Policy checkbox is checked. Checking this box attaches the policy to the Flow.
    • Leave the Flow drop-down menu set to the default value of Flow PreFlow, Proxy Endpoint default.
    • Ensure that Request is set for the Segment.
  6. Click Add. The new policy is attached to the PreFlow flow of a request.
  7. Ensure that the PreFlow flow is selected in the left side of the API Proxy Editor.
  8. 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.
  9. 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.
  10. Click Save to save the current revision with your changes.
  11. Make a request to the API in your Web browser by entering the following, substituting your Apigee organization name for {org-name}:

    http://{org-name}-test.apigee.net/v1/weather/forecastrss?w=12797282

    For example:

    http://myorg-test.apigee.net/v1/weather/forecastrss?w=12797282

    Make sure the request succeeds and you see weather information.
  12. 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"}}}
  13. 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.
  14. 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 is changed to application/json. The policy only works when the source content-type 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 New policy, and select XML to JSON in the Mediation category.
  5. In the New Policy dialog select the following:
    • Keep the default values for Policy Name and Attach Policy.
    • In the Flow drop-down menu, select Flow PostFlow, Proxy Endpoint default.
    • Select the Response option for Segment.
  6. Click Add. Because you selected Flow PostFlow, Proxy Endpoint default, and chose the Response segment, 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.
  7. Click Save.
  8. Request the URL of the API in a browser to see that the response is now formatted as JSON:

    http://{org-name}-test.apigee.net/v1/weather/forecastrss?w=12797282

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?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)