Edit your API proxy

Was this helpful?

The API Proxy Editor enables you to modify the behavior of proxied APIs by configuring and attaching policies to request and response Flows. It also allows you to customize the underlying configuration of an API proxy. You can, for example, set up conditional Flows to support dynamic behavior or add Endpoints to support advanced traffic management scenarios.

Using the API Proxy Editor, you can:

  • Configure and attach policies to Flows
  • Create and customize Endpoints
  • Configure message routing
  • Specify Conditional Flows and conditional policy execution
Back to top

Examining the API Proxy Editor

The proxy editor is divided into four main views:

  • Navigator. Lists the policies in the proxy, as well as the proxy’s Endpoints and scripts.
  • Designer. Displays a model of a selected Flow in the API’s request and response Flows, and the policies attached to that Flow.
  • Code. Shows the XML configuration for a selected policy or Flow, or if a script is selected, displays the JavaScript or Python script.
  • Property Inspector. Lists the XML configuration elements and attributes for a selected policy or Flow.

As you edit your API with the proxy editor, you’ll be able to take advantage of all of these views.

Back to top

Configuring and attaching policies

A typical way of editing an API proxy is to attach out-of-the-box policies provided by the API Platform to Flows in the API proxy. For example, you can attach a Spike Arrest policy to a Flow to manage traffic spikes.

Looking for a list of all policies? See the Policy Reference

To attach a policy to a Flow:

  1. In the API proxy editor, click New Policy.

    This displays a categorized list of all the policies you can create.

  2. Select the policy you want to add to the API proxy.

    For example, if you want to add a SpikeArrest policy, select Traffic Management category in the policy dropdown menu.

  3. Modify the selections in the New Policy dialog to configure and attach the policy.

    If you accept the default selections, as shown below, the policy will be enforced on request messages from client apps to the ProxyEndpoint PreFlow.

    The default selection of 'Flow PreFlow, Proxy Endpoint default' attaches the policy you created to the PreFlow of the ProxyEndpoint named 'default'. That means that the policy will execute in the ProxyEndpoint’s PreFlow.

    The interaction between this setting and the next setting is critical. You typically would require a SpikeArrest policy to be enforced on request messages. Therefore, you should select the Request segment. This sets the policy enforcement point to be on request messages from client apps to the ProxyEndpoint PreFlow.

    You can change this setting to have the policy execute at a different point in the processing Flow. For example, to have the policy execute instead in the PostFlow of the default ProxyEndpoint, select Flow PostFlow, Proxy Endpoint default.

    Note: If you don’t check the Attach Policy checkbox, the policy will not be attached to a Flow. You might do this if you simply want to configure a policy and later decide its attach points. You can attach the policy later by selecting it in the Navigator view and then clicking Attach Policy.

  4. Click Add.

    The policy is attached to the Flow that you selected. For example, if you created a Spike Arrest policy and attached it to the PreFlow of the default ProxyEndpoint, you’ll see the policy displayed in the Designer view for the PreFlow of the default ProxyEndpoint.

  5. In the Navigator view, click the Flow to which you added the policy.

    For example, if you added the policy to the PreFlow of the default ProxyEndpoint, expand Proxy Endpoints. Then expand default. Click PreFlow.

    You’ll see the XML definition for the PreFlow in the Code view. Notice it identifies the Spike Arrest policy in the Flow.

    <flowbean name="PreFlow">
    <request><step>
    <faultrules>
    <name>SpikeArrest-1361307099688</name>
</faultrules></step></request>
    <response>
</response></flowbean>

To remove a policy from a Flow: Mouse over the icon for the policy in the Designer view of the pertinent Flow. Click the X in the circle that appears in the icon.

To remove a policy: 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.

Back to top

Further configuring policies

After you attach a policy, you can further configure it 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.

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.

Some policies expose XML elements that can have multiple subelements. For example, the AssignMessage policy (which is used in the request or response path to generate a new message or to modify an existing message) exposes various elements in which multiple query parameters can be specified. In these cases, the Property Inspector displays an (+) icon. Click the icon to add entry fields for additional subelements.

Back to top

Configuring Flow behavior using scripts

Using out-of-the-box policies is one way of controlling the behavior of Flows in your API proxy. Another way is to use scripts. This gives you the ability to execute either JavaScript or Python scripts for the Flow, and in this way invoke customized behavior. You can also use XSL transformations to customize behavior. Although not technically scripts, XSL transformations are listed as scripts in the proxy editor.

The API Platform defines a simple object model for working with objects in a proxy pipeline programming model. Your scripts will be implemented to this object model.

Learn about the Apigee JavaScript object model.

To add a script to to your API proxy, you need to:

  • Import the script.
  • Create a JavaScript, Python, or XSL Transform policy.
  • Associate the JavaScript or Python script with the policy. You don't have to do this for the XSL Transform policy — the association is automatically made when you create the policy.

To import the script:

  1. In the proxy editor, click New, then New Script.

    In response, you’ll see a New Script dialog that displays the name assigned to the new script, and radio buttons that identify whether the script is in compiled JavaScript, Python, or XSL Transformation format.

  2. Click Import Script. Then navigate on your local machine to the script file or XSL Transformation (XSLT) file that you want to import.

    The script name in the dialog will change to the name of the file you select.

  3. Click Add.

    The script is added to the navigator view. You’ll also see the script code in the Code view, for example:

    response.status ="200";
response.headers['X-Apigee-Test-Header-1'][0]='Test-Header 1 Value 0';
response.headers['X-Apigee-Test-Header-2'][0]='Test-Header 2 Value 0';
response.headers['X-Apigee-Test-Header-2'][1]='Test-Header 2 Value 1';
response.content='This is your code on Apigee!';

To create a script policy:

  1. In the proxy editor, click New Policy.

    This displays a categorized list of all the policies you can create.

  2. Select either the JavaScript or Python policy in the Extension category, or the XSL Transform policy in the Mediation category.

    In response, you’ll see a New Policy dialog that displays the Policy Name assigned to the new policy, an Attach Policy checkbox, a Flow drop-down menu, and Segment request and response radio buttons. For an XSL Transform policy, you'll also see a Script File drop-down menu with the XSLT file that you imported already selected.

  3. Change the selections in the New Policy dialog, as needed.

    For example, if you want to attach the policy to the PostFlow of the default ProxyEndpoint, select Flow PostFlow, Proxy Endpoint default.

  4. Click Add.

    The policy is added to the Flow that you selected.

To associate the JavaScript or Python script with the policy:

  1. In the Navigator view, click the script policy that you imported.

    You’ll see its XML definition in the Code view and its property and attribute values in the Property Inspector.

  2. Add the name of the script to the value of the <ResourceURL> element in the XML.

    Place the name after the ResourceURL prefix (such as jsc://). Alternatively, you can add the name of the script to the ResourceURL value in the Property Inspector (here too add it after the ResourceURL prefix). For example:

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript timeLimit="200" enabled="true" continueOnError="false" async="false" name="JavaScript-1361303418698">
    <DisplayName>JavaScript</DisplayName>
    <FaultRules/>
    <Properties/>
    <IncludeURL>jsc://</IncludeURL>
    <ResourceURL>jsc://JavaScript-1361303418698</ResourceURL>
</Javascript>

Learn more about customizing Flows using JavaScript in Use JavaScript to customize an API.

Back to top

Creating Endpoints

When you create an API proxy two endpoints are automatically generated: a ProxyEndpoint named 'default' and a TargetEndpoint also named 'default'. In most cases, this should meet your requirements. However, in rare cases you might need to create additional Endpoints. For example, you might create a new Endpoint as the target of conditional routing through RouteRules.

Conditional routing allows you to route a request to another endpoint if a certain condition that you specify is true. In some cases, you might conditionally route to an existing Endpoint. In other cases, you might need to create a new Endpoint and route requests there if they meet the condition. (You can even conditionally route messages to another URL and bypass any TargetEndpoint.) See Configuring Message Routing below to learn more about how conditional routing is set in RouteRules.

To create an endpoint:

  1. In the API proxy editor click New, then New Endpoint.

    In response, you’ll see a New Endpoint dialog that displays the name assigned to the new Endpoint, and radio buttons that identify whether the Endpoint is a Proxy or Target EndPoint. Proxy is selected by default.

  2. Change the selections in the New Endpoint dialog, as needed. For example, select the Target radio button if you want the endpoint be a TargetEndpoint.
  3. Click Add.

    You’ll see the Endpoint in the Navigator view. You’ll also see the XML for the Endpoint in the Code view, and the XML attribute and property values for the Endpoint in the Property view.

Back to top

Customizing Endpoints

Though you typically don’t need to do so, you have the ability to customize an Endpoint by changing its XML definition in the Code view. For example, in advanced scenarios, where you need to configure transport level HTTP settings, you can use the Code view to edit the Endpoint definition. See Endpoint properties reference for details.

When you make property changes in the Code view, the changes are also made 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.

Back to top

Configuring message routing

When you create a new proxy, the ProxyEndpoint contains a default RouteRule. The RouteRule defines where the inbound request message is forwarded after it is processed by the ProxyEndpoint PostFlow. A simple API proxy usually routes messages to a named TargetEndpoint. The TargetEndpoint in the default RouteRule is the default TargetEndpoint.

You can add RouteRules to support conditional routing. In each new RouteRule, you specify a condition and a target. The target can be a TargetEndpoint (or even a URL, which bypasses any TargetEndpoint). If the condition evaluates to true, the request is forwarded to the target you specify. If the condition is not true, the request is forwarded to the default Target Endpoint.

Here’s what the XML for a RouteRule with conditional routing might look like:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ProxyEndpoint name="default">
    <Description>Default Proxy to create flows on an API</Description>
    <FaultRules/>
    <Flows>
    <HTTPProxyConnection>
        <BasePath>/test</BasePath>
        <Properties/>
        <VirtualHost>default</VirtualHost>
    </HTTPProxyConnection>
    <RouteRule name="default">
    <!==this routing executes if the header indicates that this is an XML call. If 
    true, the call is routed to the endpoint XMLTargetEndpoint==>
        <Condition>request.header.content-type = "text/xml"</Condition>
        <TargetEndpoint>XmlTargetEndpoint</TargetEndpoin>>
    </RouteRule>
</ProxyEndpoint>
Back to top

Specifying conditional Flows and policies

You might want a Flow to be processed only if a certain condition is true. For example, "Execute the Flow only if the request path starts with the term status." Or you might need a specific policy to be enforced conditionally. For instance, "If the request is of the type SOAP, enforce Policy X, if the type is REST, enforce Policy Y." You can set up a conditional Flow or enforce a policy conditionally using the proxy editor.

To create a conditional Flow:

  1. In the proxy editor, click New.
  2. Select New Conditional Flow in the drop-down menu.

    In response, you’ll see a New Conditional Flow dialog that displays the name assigned to the new conditional Flow, an empty Condition text area, and an Add to Endpoint drop-down menu, with Proxy endpoint default initially selected.

  3. Enter a condition in the Condition text area and change the Add to Endpoint selection, if necessary.

    For example, the following adds a conditional Flow to the default ProxyEndpoint. The flow is executed only if the request path starts with the term "statuses":

    To learn more about conditions, see Create dynamic API flows using conditions.

To enforce a policy conditionally, specify the condition in a <Condition> element within the XML for the Flow. For example, the following enforces an XMLtoJSON policy only if the Accept field in the HTTP request-header has the value "application/json".

<flowBean name="PostFlow">
    <Request/>
    <Response>
        <Step>
            <FaultRules/>
            <Condition>request.header.content-type = "application/json"</Condition>
            <Name>XMLtoJSON-1361313483519</Name>
        </Step>
    </Response>
</flowBean>
Back to top

Adding resources

When you create an API, you can optionally specify API resources. By defining specific resources, you gain the ability to apply policies to the URIs that represent those resources, as well as operational visibility into the performance or consumption of those URIs. You can also add resources to the API through the proxy editor.

To add a resource:

  1. In the proxy editor, click New.
  2. Select New Resource in the drop-down menu.

    In response, you’ll see a New Resource dialog with drop-down menus for you to select a resource verb and an Endpoint for you to add the resource (Proxy endpoint default is initially selected). The dialog also displays text fields for you to enter a resource name, path, and description.

  3. Make appropriate selections and entries in the dialog. For example, the following adds a resource named news with path /news. It also associates the HTTP verb GET with the resource.

  4. Click Add.

    The resource is added as a Flow to the Endpoint that you selected. You can then add policies to the Flow as appropriate. Notice that the XML for the resource’s Flow in the Code view defines a condition that tests for the specified path value and verb. If the condition is true, the API platform applies the policies in the resources Flow.

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Flow name="news">
    <Description>Weather news</Description>
    <Request/>
    <Response/>
    <Condition>(proxy.pathsuffix MatchesPath "/news") and (request.verb = "GET")</Condition>
</Flow>
Back to top

Deploying a revision

You won't see the effects of your changes until you save them and deploy the API. To save your changes, click the Project button, then select Save in the drop-down menu. To deploy the API, click Deployment, then select either the test or prod environment. Your updated API replaces the current revision deployed in the selected environment.

Note: Depending on your role, you may not be able to deploy to all environments. Users can only deploy to the test environment. If you're an administrator you can deploy to any environment.

You can also deploy multiple revisions of an API. It's common to have a revision in prod while another revision is in test as it is being tested or developed.

To add a revision, click the Project button, then select Save as New Revision in the drop-down menu. Then deploy the new revision by clicking Deployment and then test or prod.

Be careful when you deploy a revision because it overwrites the existing revision in the selected environment. Even though you can create multiple revisions, each environment can only have one deployed revision of an API. So you can have revision 2 in test and revision 1 in prod, but you can’t have both revisions in the same environment. Also, be cautious when deploying to your production environment as the updates may affect customers.

Back to top

Tracing your flow

It's a good idea to validate your API flow before deploying it into production. After you configure and deploy the API, you can send a few requests and trace them. To trace calls, you need to start a tracing session — something you can do in the proxy editor.

To start a tracing session in the test environment, click Trace, then select test in the drop-down menu. This opens a Trace page which shows you the response size and round trip time of the request and response. This allows you to optimize responses for size and latency before you actually deploy the API in a production environment.

In most cases you want to sample live data. When you trace the API calls, you see the results of a number of live calls that have gone through your API. This is historical data, as the messages have already occurred. The calls can come from any application using your API, so it's a good way to see how your API is performing in the real world. See Troubleshoot API traffic using Trace for more details.

See also

How an API proxy works

Back to top