Step 5: Add a policy

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

Now that you've changed your target endpoint, you're ready to add a policy to your proxy.

A policy is an Apigee component that you can attach to different points in the message flow through your API proxies. Policies can transform message formats, enforce access control, call remote services, authorize users, examine message content for potential threats, and do much more.

In this tutorial, you're going to add the XMLtoJSON policy to your proxy. This policy converts the payload of an XML message to JSON. It also changes the response's Content-Type header.

You can attach a policy to a flow in the proxy. Flows control how policies are executed. In this example, you'll add the policy to a special flow, called the PreFlow. Policies in the PreFlow, are executed before any other policies in the proxy. While you don't need to understand flows in detail to read this example, you can learn more about them in Controlling API proxies with flows.

Further Reading

There are dozens of out-of-the-box policies that you can add to your proxies, including:

• AssignMessage policy
• RaiseFault policy
• JavaScript policy
• SpikeArrest policy
• ExtractVariables policy

For a complete list of policies, see Policy reference.

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

There are two steps to add the XMLtoJSON policy to your proxy:

• Create an instance of the policy.
• Attach the policy to a step in the PreFlow.

Create an instance of the policy

To use a policy, you first have to create a new instance of the policy from the policy template as follows:

1. If you are using the Apigee UI in Cloud console: Select Proxy development > API Proxies.

   If you are using the classic Apigee UI: Select Develop > API Proxies and in the Proxies pane, select the environment for the proxy.

2. From the proxies list, select the proxy in which you want to add the policy.

3. Click the Develop tab.

4. In the left-hand pane, click the + button next to the Policies folder.
5. In the Create policy dialog, select Standard policies to filter the available policy list by policy type.
6. In the Select policy type text box, scroll down to Mediation and select XML To JSON.

7. Optionally, you can change the Name and Display name of the policy. By default, Apigee provides a short prefix for the policy name, in this case, X2J-, You can add a sequence of descriptive words separated by dashes, after the prefix. See Naming conventions.

   

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

The XML To JSON policy is now displayed in the right-hand pane of the Develop view:

The lower half of the pane displays the XML code for the policy.

To learn more about the policy, select the information icon next to the policy name and click XML To JSON policy. This displays the reference page for the policy.

Use Gemini Code Assist to review policy instructions

If you have the Gemini Code Assist add-on, you can highlight a policy element to see information about that element and how to use it. See Use Gemini Code Assist code explain with policies for information.

Change the policy name

To change the name of a policy:

1. Select the policy under Policies in the left-hand pane.
2. In the <DisplayName> element in the XML code for the policy, add a descriptive phrase for the policy, such as change-xml-to-json, after the abbreviation for the policy name:

   

   This automatically updates the policy name, displayed under Policies.

   See Naming conventions.

Attach the policy to a step in the PreFlow

Now that you have created the XML To JSON policy, you can attach it to a step in the PreFlow:

1. Select Proxy Endpoints > default > PreFlow in the left-hand pane:

   

   Note: You may need to expand the visual editor in the right-hand pane to see all the elements. To do so, click and drag the divider between the visual editor and the text editor down a little.

2. Click the + button next to PreFlow in the Response pane at the bottom-right of the visual editor:

   

3. In the Add policy step dialog, select the X2J-change-xml-to-json policy.

4. Click Add to attach the policy.

   The X2J-change-xml-to-json policy is now displayed in the Response pane:

   

5. Click Save to save the current revision with your changes.
6. To deploy your changes to the revision, click Deploy and follow the instructions in Deploy an API proxy.

Classic Proxy Editor

To add the XMLtoJSON policy to your proxy:

1. Open the Apigee UI in a browser and log in.
2. Click API Proxies in the main window and select a proxy. For this example, select the proxy that you created in Step 2: Create an API proxy.

3. Click the Develop tab:

   

   Apigee displays the API Proxy Editor.

4. In the Navigator pane, click Proxy Endpoints > default > PreFlow:

   

   Apigee displays the Flow editor:

   

   In addition, Apigee displays the default Proxy Endpoint configuration in the Code pane:

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <ProxyEndpoint name="default">
     <Description/>
     <FaultRules/>
     <PreFlow name="PreFlow">
       <Request/>
       <Response/>
     </PreFlow>
     <PostFlow name="PostFlow">
       <Request/>
       <Response/>
     </PostFlow>
     <Flows/>
     <HTTPProxyConnection>
       <BasePath>/myproxy</BasePath>
       <Properties/>
       <VirtualHost>default</VirtualHost>
       <VirtualHost>secure</VirtualHost>
     </HTTPProxyConnection>
     <RouteRule name="default">
       <TargetEndpoint>default</TargetEndpoint>
     </RouteRule>
   </ProxyEndpoint>

5. To add a policy to your proxy, click the + Step button in the response PreFlow (the bottom half of the Flow editor):

   

   Apigee displays a categorized list of policies in the Add dialog box that you can add to your flow:

   

6. Scroll down and select the XMLtoJSON policy in the Mediation category.
   TIP: The API Proxy Editor also supports drag & drop. For example, after you have added one or more policies to the proxy, you can then drag them from the Navigator into place in the Flow editor:

   

7. Leave the default names, and click Add.

   Apigee attaches the new policy to the PreFlow of the response:

   

   Note that when you click Add, Apigee does the following:

   • Adds the new policy under Policies in the Navigator pane.
   • Adds the XMLtoJSON policy in the Flow pane.
   • Displays the policy's configuration XML in the Code pane.
8. Click Save to save the current revision with your changes.
9. To deploy your changes, click the Overview tab and click the Deploy button.

Test the new policy

To test the new policy, execute the following curl command in a terminal window:

curl https://YOUR_ENV_GROUP_HOSTNAME/myproxy

where YOUR ENV_GROUP_HOSTNAME is the environment group hostname. See Find the environment group hostname.

See Call your API proxy for more information.

Alternatively, you can open the same URL in a browser.

You should receive the following response:

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

If the body of the response doesn't look like this, check that:

1. Your target endpoint is https://mocktarget.apigee.net/xml, as described in Step 4: Change your target endpoint:
   • If you get Hello, Guest! as a response, then you need to append /xml to the end of the target endpoint.
   • If you get a 404, then check that you are accessing apigee.net and not apigee.com.
2. The latest revision of your proxy is deployed. Try re-deploying your API proxy as described in Deploying an API proxy and Undeploying an API proxy.

To see the HTTP request and response headers, enable verbosity in curl with the -vs option (v makes the response verbose, but s suppresses some of the less interesting details). The following example assumes that the proxy is named myproxy::

curl -vs https://YOUR_ENV_GROUP_HOSTNAME/myproxy  | python -m json.tool

You should get a response that looks like the following. Note that the Content-Type header in the response is application/json. The XMLtoJSON policy changes the header before sending the response back.

*   Trying 10.20.30.40...
* TCP_NODELAY set
* Connected to apitest.acme.com (10.20.30.40) port 443 (#0)
...
> GET /myproxy HTTP/1.1
> Host: apitest.acme.com
> User-Agent: curl/7.58.0
> Accept: */*
>
< HTTP/1.1 200 OK
< Date: Fri, 25 May 2018 16:20:00 GMT
< Content-Type: application/json;charset=UTF-8
< Content-Length: 77
< Connection: keep-alive
< X-Powered-By: Apigee
< Access-Control-Allow-Origin: *
...
{ [77 bytes data]
{
  "root": {
    "city": "San Jose",
    "firstName": "John",
    "lastName": "Doe",
    "state": "CA"
  }
}

Next step

Go deeper