Send Docs Feedback

Add policies to your API

What you'll learn

Through this tutorial, you'll learn to:

  • Create an API proxy.
  • Add policies that affect the request and response.
  • See the effects of the policies.
  • View message details in the Trace tool.

Apigee Edge provides a lot of built-in functionality for managing traffic between clients and your target services, such as security, traffic limiting, and message transformation. This functionality is handled through policies that you attach to different points in the message flow through your API proxies. With policies, you can augment your target services without having to modify them.

In this tutorial, you'll create an API proxy that does two things:

  • Protects against sudden traffic spikes
  • Transforms a response from XML to JSON

You'll make calls to the API proxy to see the policy behavior in action, then view message details in the Trace tool.

What you'll need

  • An Apigee Edge account. If you don't have one yet, you can sign up with the directions at Creating an Apigee Edge account.
  • cURL installed on your machine to make API calls from the command line.

Create the API proxy

About the 'mocktarget'

The mocktarget service is hosted at Apigee and returns simple data. It requires no API key or access token. In fact, you can access it in a web browser. Try it out by clicking the following:

The target returns Hello, Guest!. Use the /help resource to get a help page of other API resources that are available.

  1. Go to and log in. This is the Edge management UI.
  2. Click APIs in the top menu.
  3. Click the add (+) API Proxy button.
  4. In the Build a Proxy wizard, select Reverse proxy (most common), and click Next.
  5. Configure the proxy with the following:
    In this field do this
    Proxy Name Enter: helloworld_policies
    Project Base Path

    Change to: /v1/hellopolicies

    The Project Base Path is part of the URL used to make requests to the API proxy.

    Adding a version number is considered a best practice to version your API. For more information on this important topic, see Versioning Best Practices.

    Existing API


    Be sure to use http and not https. This defines the target URL that Apigee Edge invokes on a request to the API proxy. The /xml resource returns a sample XML response.

    Description Enter: hello world with policies
  6. Click Next.
  7. On the Security page, select Pass through (none) as the security option, and click Next.
  8. On the Virtual Hosts page, click Next.
  9. On the Build page, make sure the test environment is selected, and click Build and Deploy.
  10. On the Summary page, you see an acknowledgment that your new API proxy was created successfully and deployed to your test environment.
  11. Click View the helloworld_policies proxy in the editor to display the Overview page for the API proxy.

Test the initial API proxy

In a terminal window, run the following cURL command, substituting your organization name:

curl "http://{org-name}"

You should see something like the following for the response:

<?xml version="1.0" encoding="UTF-8"?> <root><city>San Jose</city><firstName>John</firstName><lastName>Doe</lastName><state>CA</state></root>

You can also hit the URL in a web browser to see the response in a tidier format.

At this point, calling your API proxy gives you the same result as if you directly call the target service with But the API proxy response will change after you add policies in the next steps.

Spike Arrest policy

In this step, you'll add and configure the Spike Arrest policy to guard the target service against sudden traffic spikes 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.

Add the Spike Arrest policy to an API proxy:

  1. In the editor for the new API proxy, click the Develop tab.
    (If you're not in the API proxy editor, select APIs > API Proxies > helloworld_policies in the management UI menu.)

    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 request and response message flow as well as an editable display of the underlying XML that defines the proxy.

  2. In the left Navigator pane, click PreFlow under Proxy Endpoints > default. (Other tutorials will cover the concept of flows.)
  3. Click the top +Step button, corresponding to the Request PreFlow. This displays a categorized list of all the policies you can create.
    Click Step in Request PreFlow
  4. Select Spike Arrest in the Traffic Management category. The New Policy dialog appears:
    Create Spike Arrest policy
  5. Leave the default names, and click Add. The new policy is attached to the PreFlow flow of a request.
  6. In the Navigator, ensure that PreFlow under Proxy Endpoints > default is still selected and note the following in the API Proxy Editor:
    • The new Spike Arrest-1 policy is added under Policies in the Navigator in the left side of the API Proxy Editor.
    • The Spike Arrest-1 icon 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.
    • The XML for the policy is displayed in the Code view in the bottom center of the API Proxy Editor.
    View PreFlow with Spike Arrest policy
  7. In the Navigator, select Spike Arrest-1 under Policies and note the following in the API Proxy Editor:
    • The policy details are displayed in the Designer view in the top center of the API Proxy Editor.
    • 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 in the right side of the API Proxy Editor.
  8. In the XML for the policy, change the value of the <Rate> element to 1pm (which translates into roughly 2 requests allowed every 60 seconds in the cloud).

    The behavior of Spike Arrest involves a smoothing algorithm across multiple message processors, which affects the actual behavior your see. If you want more details, see the Spike Arrest policy reference topic.

    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. Alternatively, you can change the Rate value in the Property Inspector and it will be reflected in the XML view.

  9. Click Save to save the current revision with your changes.
  10. Call the API again using cURL, substituting your Apigee organization name for {org-name}:

    curl "http://{org-name}"

    Make sure the request succeeds and you see the same XML response as you did previously. (You can also enter just the URL in a web browser.)

  11. Run the cURL command (or refresh the browser window) two or three more times within one minute, and notice that you get the following message because you exceeded the rate limit of the policy:

    {"fault":{"faultstring":"Spike arrest violation. Allowed rate : 1pm","detail":{"errorcode":"policies.ratelimit.SpikeArrestViolation"}}}

    If you try making more calls within a minute, you should continue to get the fault message.

  12. Edit your policy to set the <Rate> limit to 15pm (which translates into roughly 2 calls allowed every 4 seconds in the cloud), and then save the API proxy.
  13. Run the cURL command or refresh the browser repeatedly (cURL is faster). Notice that if you make one or two calls within 4-second intervals, your calls succeed. If you make the calls quickly, more than two in within 4 seconds, you should get the fault. But after each 4-second interval you can continue making calls, as opposed to being blocked out for an entire minute (with the 1pm setting).

XML to JSON Policy

The response from the sample target 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 the target 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 API Proxy Editor, click PostFlow under Proxy Endpoints > default to add the policy to that flow.
  2. Click the bottom +Step button, corresponding to the Response PostFlow. This displays a categorized list of all the policies you can create.
  3. Select XML to JSON in the Mediation category.
  4. In the New Policy dialog, keep the default values for Display Name and Name.
  5. 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 > default in the Navigator. To see the Spike Arrest policy, select PreFlow under Proxy Endpoints > default.
    View Preflow with XML to JSON policy
  6. Click Save.
  7. Call the API again using cURL (or just the URL in a web browser), substituting your organization name for {org-name}:

    curl "http://{org-name}"

    Notice the response is now in JSON.

    {"root":{"city":"San Jose","firstName":"John","lastName":"Doe","state":"CA"}}

Way to go! You've created an API proxy and added policies to it that protect against traffic spikes and convert an XML response to JSON—all without touching the target service.

View the message data with Trace

The API proxy Trace tool lets you view headers, variables, objects, and other details such as response time in the API proxy request and response flow. The Trace tool also lets you see how a request or response changes as it is processed by an API proxy.

Earlier in the tutorial, we mentioned that the Content-Type changed from application/xml to application/json after the XML to JSON policy was executed. In this step, we'll use the Trace tool to view this change, view the initial response body (XML) and the modified body (JSON), and see other interesting details.

  1. On the Develop tab of the API proxy, edit the Spike Arrest policy's <Rate> to be 1pm again, then Save the proxy. This will allow us to see both successful and failed (over the limit) API calls.
  2. In the API proxy editor, click the Trace tab.
  3. Click Start Trace Session.
  4. Call the API proxy again using cURL (or with the URL in a web browser) until you see at least one 200 response and one 500 response in the Transactions pane of Trace.

    curl "http://{org-name}"

  5. Click Stop Trace Session.
  6. Click the 200 transaction in the left Transactions pane. Its Trace detail is loaded in the main window under Transaction Map, which shows a request/response diagram. The Spike Arrest icon is in the request flow, and the XML to JSON icon is in the response flow.
  7. In the flow diagram, click the circle icon in the response, the furthest one to the right (shown in the following diagram).

    The Phase Details pane shows the data available at that point in the flow. If you scroll through that pane, you'll see the HTTP response headers and body content.
    • Content-Type is application/xml, the normal response format from the target service.
    • Body shows the response content in XML.

  8. Click the XML to JSON icon in the response flow. In Phase Details, scroll to see that:
    • Content-Type has been changed to application/json by the XML to JSON policy.
    • Body is in JSON format.

  9. Now look at an error in Trace.

    Click the 500 transaction in the Transactions pane. In the main editor window, you see a flow diagram with items in the request only, including a Spike Arrest icon with a red exclamation point indicating an error.

    Click the small tube error icon to the right of the Spike Arrest icon, and look at the spike arrest violation details in the Phase Details pane.

You can click the Back and Next buttons in the flow diagram to move between points in the flow and see the Trace details.

If you want to see the entire Trace as a single document, download it by clicking Download Trace Session.

For more about Trace, see Using the Trace tool.


Help or comments?