—Rate this article—
 

API proxy configuration reference

As a developer working with the Apigee Edge, your primary development activities involve configuring API proxies that function as proxies for APIs or backend services. This document is a reference of all configuration elements available to you when building API proxies. 

If you are learning how to build API proxies, it is recommended that you begin with the topic  Build a simple API proxy.

API proxy structure

An API proxy consists of the following configuration:

Base Configuration Primary configuration settings for an API proxy. See Base Configuration.
ProxyEndpoint Configuration Settings for the inbound HTTP connection (from requesting apps to Apigee Edge), request and response flows, and policy attachments. See ProxyEndpoint.
TargetEndpoint Configuration Settings for the outbound HTTP connection (from Apigee Edge to the backend service), request and response flows, and policy attachments. See TargetEndpoint.
Flows ProxyEndpoint and TargetEndpoint request and response pipelines to which polices can be attached. See Flows.
Policies XML-formatted configuration files that conform to the Apigee Edge policy schemas. See Policies.
Resources Scripts, JAR files, and XSLT files referenced by policies to execute custom logic. See Resources.

API proxy directory structure and contents

The components in the table above are defined by configuration files in the following directory structure:

Configuration files and directory structure of an API proxy

This section explain the configuration files and directory structure of an API proxy.

Base Configuration

/apiproxy/weatherapi.xml

The base configuration for an API proxy, which defines the name of the API proxy. The name must be unique within an organization.

Sample configuration:

<APIProxy name="weatherapi">
</APIProxy>

Base Configuration Elements

Name Description Default Required?
APIProxy  
name The name of the API proxy, which must be unique within an organization. The characters you are allowed to use in the name are restricted to the following: A-Z0-9._\-$ % N/A Yes
revision The revision number of the API proxy configuration. You do not need to explicitly set the revision number, since Apigee Edge automatically tracks the current revision of the API proxy. N/A No
ConfigurationVersion The version of the API proxy configuration schema to which this API proxy conforms. The only supported value currently is majorVersion 4 and minorVersion 0. This setting may be used the in the future to enable evolution of the API proxy format. 4.0 No
Description A textual description of the API proxy. If provided, the description will display in the Edge management UI. N/A No
DisplayName A user-friendly name that may be different from the name attribute of the API proxy configuration. N/A No
Policies A list of policies in the /policies directory of this API proxy. You will normally only see this element when the API proxy was created using the Edge management UI. This is simply a 'manifest' setting, designed to provide visibility into the contents of the API proxy. N/A No
ProxyEndpoints A list of ProxyEndpoints in the /proxies directory of this API proxy. You will normally only see this element when the API proxy was created using the Edge management UI. This is simply a 'manifest' setting, designed to provide visibility into the contents of the API proxy. N/A No
Resources A list of resources (JavaScript, Python, Java, XSLT) in the /resources directory of this API proxy. You will normally only see this element when the API proxy was created using the Edge management UI. This is simply a 'manifest' setting, designed to provide visibility into the contents of the API proxy. N/A No
TargetServers A list of TargetServers referenced in any TargetEndpoints of this API proxy. You will normally only see this element when the API proxy was created using the Edge management UI. This is simply a 'manifest' setting, designed to provide visibility into the contents of the API proxy. N/A No
TargetEndpoints A list of TargetEndpoints in the /targets directory of this API proxy. You will normally only see this element when the API proxy was created using the Edge management UI. This is simply a 'manifest' setting, designed to provide visibility into the contents of the API proxy. N/A No

ProxyEndpoint

/apiproxy/proxies/default.xml

The ProxyEndpoint configuration defines the inbound (client-facing) interface for an API proxy. When you configure a ProxyEndpoint, you are setting up a network configuration that defines how client applications ('apps') should invoke the proxied API.

The following sample ProxyEndpoint configuration would be stored under /apiproxy/proxies:

<ProxyEndpoint name="default">
    <HTTPProxyConnection>
        <BasePath>/weather</BasePath>
        <VirtualHost>default</VirtualHost>
    </HTTPProxyConnection>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

The required configuration elements in a basic ProxyEndpoint are:

ProxyEndpoint Configuration Elements

Name Description Default Required?
ProxyEndpoint  
name The name of the ProxyEndpoint. Must be unique within the API proxy configuration, when (in rare cases) multiple ProxyEndpoints are defined. The characters you are allowed to use in the name are restricted to the following: A-Z0-9._\-$ %. N/A Yes
HTTPProxyConnection Defines the network address and URI path associated with the API proxy
BasePath

A required string that uniquely identifies the URI path used by Apigee Edge to route incoming messages to the proper API proxy.

The BasePath is a URI fragment (for example /weather) appended to the base URL for an environment (for example, http://apifactory-test.apigee.net) by a requesting client. BasePath must be unique within an environment. Uniqueness is validated by API Services when an API proxy is generated or imported.

/ Yes
VirtualHost

Associates an API proxy with specific base URLs for an environment. A VirtualHost is a named configuration that defines one or more URLs for an environment.

The named VirtualHosts defined for a ProxyEndpoint determine the domains and ports on which an API proxy is exposed, and, by extension, the URL that apps use to invoke an API proxy.

By default, two named VirtualHosts are defined for an environment: default and secure. An organization may also define custom domains. To ensure that an API proxy is available only over HTTPs, for example, set the VirtualHost in the HTTPProxyConnection to secure.

default Yes
Properties A set of optional HTTP configuration settings can be defined as properties of a ProxyEndpoint. See Endpoint properties reference. N/A No
DefaultFaultRule

Handles any errors (system, transport, messaging or policy) that are not explicitly handled by another FaultRule.

See Fault handling.

N/A No
RouteRule Defines the destination of inbound request messages after processing by the ProxyEndpoint request pipeline. Usually, the RouteRule points to a named TargetEndpoint configuration, but it can also point directly to a URL.
Name Required attribute, which provides a name for the RouteRule. The characters you are allowed to use in the name are restricted to the following: A-Z0-9._\-$ %. For example, Cat2 %_ is a legal name. N/A Yes
Condition An optional conditional statement used for dynamic routing at runtime. Conditional RouteRules are useful, for example, to enable content-based routing to support backend versioning. N/A No
TargetEndpoint

An optional string that identifies a named TargetEndpoint configuration. A named TargetEndpoint is any TargetEndpoint defined in the same API proxy under the /targets directory).

By naming a TargetEndpoint, you indicate where request messages should be forwarded after processing by the ProxyEndpoint request pipeline. Note that this is an optional setting.

A ProxyEndpoint may call a URL directly. For example, a JavaScript or Java resource, functioning in the role of an HTTP client, may perform the basic duty of a TargetEndpoint, which is to forward requests to a backend service.

N/A No
URL An optional string that defines an outbound network address called by the ProxyEndpoint, bypassing any TargetEndpoint configurations that might be stored under /targets N/A No

How to configure RouteRules

A named TargetEndpoint refers to a configuration file under /apiproxy/targets to which the RouteRule forwards a request after processing by the ProxyEndpoint.

For example, the following RouteRule refers to the configuration /apiproxy/targets/myTarget.xml:

<RouteRule name="default">
  <TargetEndpoint>myTarget</TargetEndpoint>
</RouteRule>

Direct URL Invocation

A ProxyEndpoint can also directly invoke a backend service. Direct URL invocation bypasses any named TargetEndpoints configuration under /apiproxy/targets). For this reason, TargetEndpoint is an optional API proxy configuration, although, in practice, direct invocation from the ProxyEndpoint is not recommended.

For example, the following RouteRule makes an HTTP call to http://api.mycompany.com/v2.

<RouteRule name="default">
  <URL>http://api.mycompany.com/v2</URL> 
</RouteRule>

Conditional Routes

RouteRules can be chained to support dynamic routing at runtime. Inbound requests can be routed to named TargetEndpoint configurations, directly to URLs, or to a combination of the two, based on HTTP headers, message content, query parameters, or contextual information such time of day, locale, etc.

Conditional RouteRules work like other conditional statements on Apigee Edge. See Conditions reference and Variables reference.

For example, the following RouteRule combination first evaluates the inbound request to verify the value of an HTTP header. If the HTTP header routeTo has the value TargetEndpoint1, then the request is forwarded to the TargetEndpoint named TargetEndpoint1. If not, then the inbound request is forwarded to http://api.mycompany.com/v2.

<RouteRule name="MyRoute">
  <Condition>request.header.routeTo = "TargetEndpoint1"</Condition>
  <TargetEndpoint>TargetEndpoint1</TargetEndpoint>
</RouteRule>
<RouteRule name="default">
  <URL>http://api.mycompany.com/v2</URL>
</RouteRule>

Null Routes

A null RouteRule can be defined to support scenarios in which the request message does not need to be forwarded to the TargetEndpoint. This is useful when the ProxyEndpoint performs all of the necessary processing, for example by using JavaScript to call an external service or retrieving data from a lookup to the API Services' key/value store.

For example, the following defines a null Route:

<RouteRule name="GoNowhere"/>

Conditional null Routes can be useful. In the following example, a null Route is configured to execute when an HTTP header request.header.X-DoNothing have a value other than null.

<RouteRule name="DoNothingOnDemand">
  <Condition>request.header.X-DoNothing != null</Condition>
</RouteRule>

Remember, RouteRules can be chained, so a conditional null Route would typically be one component of a set of RouteRules designed to support conditional routing.

A practical use of a conditional null Route would be in support of caching. By using the value of the variable that is set by the Cache policy, you can configure an API proxy to execute the null Route when an entry is served from the cache.

<RouteRule name="DoNothingUnlessTheCacheIsStale">
  <Condition>lookupcache.LookupCache-1.cachehit is true</Condition>
</RouteRule>

TargetEndpoint

TargetEndpoint is the outbound equivalent of the ProxyEndpoint. A TargetEndpoint functions as an HTTP client to a backend service or API--it sends requests and receives responses. An API proxy can contain zero or more TargetEndpoints. (ProxyEndpoints can be configured to call URLs directly --an API proxy with no TargetEndpoints usually contains a ProxyEndpoint that either directly calls a backend service, or that is configured to call a service using Java or JavaScript.)

TargetEndpoint Configuration

/targets/default.xml

The TargetEndpoint defines the outbound connection from Apigee Edge to a backend service.

Sample TargetEndpoint configuration:

<TargetEndpoint name="default">
  <HTTPTargetConnection>
    <URL>http://weather.yahooapis.com</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

TargetEndpoint Configuration Elements

Name Description Default Required?
TargetEndpoint  
name The name of the TargetEndpoint, which must be unique within the API proxy configuration. The name of the TargetPoint is used in the ProxyEndpoint RouteRule to direct requests for outbound processing. The characters you are allowed to use in the name are restricted to the following: A-Z0-9._\-$ % N/A Yes
HTTPTargetConnection  
URL Defines the network address of the backend service to which the TargetEndpoint forwards request messages. N/A No
LoadBalancer

Defines one or more named TargetServer configurations. Named TargetServer configurations can be used for load balancing defining 2 or more endpoint configuration connections.

You can also use TargetServers to decouple API proxy configurations from concrete backend service endpoints URLs.

See Load balance API traffic across multiple backend servers.

N/A No
Properties A set of optional HTTP configuration settings can be defined as properties of a TargetEndpoint. See Endpoint properties reference. N/A No
DefaultFaultRule

Handles any errors (system, transport, messaging or policy) that are not explicitly handled by another FaultRule.

See Fault handling.

N/A No
ScriptTarget  
ResourceURL

Defines the resource type (node) and the name of the main Node.js script that implements TargetEndpoint functionality.

<ResourceURL>node://server.js</ResourceURL>

ScriptTarget is an alternative to HTTPTargetConnection. (A TargetEndpoint can define either an HTTPTargetConnection or a ScriptTarget, but not both.)

See Adding Node.js to an existing API proxy.

N/A Yes
EnvironmentVariable

Optionally pass environment variables to the main Node.js script. 

See Understanding Edge support for Node.js modules.

N/A No
Arguments

Optionally pass arguments to the main Node.js script.

See Understanding Edge support for Node.js modules.

N/A No

Advanced TargetEndpoint Configuration

TargetEndpoints often need to manage HTTP connections with heterogenous backend infrastructure. For this reason, a number of advanced configuration settings are supported.

Advanced TargetEndpoint Configuration Elements

Name Description Default Required?
SSLInfo  
Enabled Indicates whether SSL is enabled for the Endpoint true Yes
TrustStore A keystore containing trusted server certificates. N/A No
ClientAuthEnabled A setting that turns on outbound client authentication (2-way SSL) false No
KeyStore A keystore containing private keys used for outbound client authentication N/A Yes (if ClientAuthEnabled is true)
KeyAlias The key alias of the private key used for outbound client authentication N/A Yes (if ClientAuthEnabled is true)
Ciphers Supported ciphers for outbound SSL N/A No
Protocols Supported protocols for outbound SSL N/A No

Sample TargetEndpoint with outbound client authentication enabled

<TargetEndpoint name="default">
  <HttpTargetConnection>
	<URL>https ://myservice.com</URL>
    <SSLInfo>
      <Enabled>true</Enabled>
      <ClientAuthEnabled>true</ClientAuthEnabled>
      <KeyStore>myKeystore</KeyStore>
      <KeyAlias>myKey</KeyAlias>
      <TrustStore>myTruststore</TrustStore>
    </SSLInfo>
  </HttpTargetConnection>
</TargetEndpoint>

For detailed instructions, refer to Configure client SSL from Apigee API Platform to your backend service

TargetEndpoint with target load balancing

TargetEndpoints support load balancing across multiple named TargetServers using three load balancing algorithms.

For detailed instructions, refer to Load balance API traffic across multiple backend servers

Policies

The /policies directory in an API proxy contains all policies available to be attached to FLows in the API proxy.

Policy Configuration Elements

Name Description Default Required?
Policy  
enabled Determines whether a policy is enforced or not. If set to false, a policy is 'turned off', and not enforced (even though the policy remains attached to a Flow) true Yes
continueOnError Most policies are expected to return an error when a failure occurs (for example, when a Quota is exceeded). By setting this attribute to true, Flow execution continues on failure. false Yes
async Enabling async=true configures Apigee Edge to run the policy in a thread pool different than the pool servicing the request/response Flow. This setting is only used for for internal optimization. Contact Apigee support at the Support Portal for more information. false Yes
name The name of the policy, which is referenced in Step elements to attach the policy to a Flow. N/A Yes

Policy Attachment

As shown above, API proxy flows execute in the following sequence:

Policies are attached as processing steps to Flows. The policy's name is used to reference the policy to be enforced as a processing Step. The format of a policy attachment is the following:

<Step><Name>MyPolicy</Name></Step>

Policies are enforced in the order in which they are attached to a Flow. For example:

<Step><Name>FirstPolicy</Name></Step>
<Step><Name>SecondPolicy</Name></Step>

Policy Attachment Configuration Elements

Name Description Default Required?
Step  
Name The name of the policy to be executed by this Step definition. N/A Yes
Condition A conditional statement that determines whether the policy is enforced or not. If a policy has an associated condition, then the policy only executes if the conditional statement evaluates to true. N/A No

Flows

ProxyEndpoint and TargetEndpoint define a pipeline for request and response message processing. A processing pipeline consists of a request flow and a response flow. Each request flow and response flow is subdivided into a PreFlow, one or more optional 'conditional' or 'named' Flow, and a PostFlow.

  • PreFlow: Always executes. Executes before any conditional Flows.
  • PostFlow: Always executes. Executes after any conditional Flows.

Additionally, the ProxyEndpoint defines a PostClientFlow which executes after the request is returned to the requesting client app. Only MessageLogging policies can be attached to the PostClientFlow. The PostClientFlow is currently used primarily for measuring the time interval between the start and end timestamps for the response message. 

The API proxy processing pipeline executes Flows in the following sequence:

Request Pipeline:

  1. Proxy Request PreFlow
  2. Proxy Request Conditional Flows (Optional)
  3. Proxy Request PostFlow
  4. Target Request PreFlow
  5. Target Request Conditional Flows (Optional)
  6. Target Request PostFlow

Response Pipeline:

  1. Target Response PreFlow
  2. Target Response Conditional Flows (Optional)
  3. Target Response PostFlow
  4. Proxy Response PreFlow
  5. Proxy Response Conditional Flows (Optional)
  6. Proxy Response PostFlow
  7. PostClientFlow Response (Optional)

Only those Flows with policy attachments need to be configured in ProxyEndpoint or TargetEndpoint configurations. PreFlow and PostFlow need only be specified in a ProxyEndpoint or TargetEndpoint configuration when a policy needs to be enforced during PreFlow or PostFlow processing.

In contrast to conditional flows, the ordering of PreFlow and PostFlow elements is not important--the API proxy will always execute each at the appropriate point in the pipeline, regardless of where they appear in the Endpoint configuration.

Conditional Flows

ProxyEndpoints and TargetEndpoints support an unlimited number of conditional flows (also known as 'named flows').

A conditional flow is executed only if the conditional statement associated with the flow evaluates to true.

For example, the following conditional statement defines an API resource /accesstoken. Any inbound request with the URI path suffix /accesstoken will cause this flow to be executed, along with any policies that are attached to the flow. Thus, this API resource functions as an OAuth token endpoint. If the inbound request URI does not include the path suffix /accesstoken, then the flow does not execute (although another conditional flow might).

<Flows>
<Flow name="TokenEndpoint">
  <Condition>proxy.pathsuffix MatchesPath "/accesstoken"</Condition>
  <Request>
    <Step><Name>GenerateAccessToken</Name></Step>
  </Request>
</Flows>

Flow Configuration Elements

Name Description Default Required?
Flow A request or response processing pipeline defined by A ProxyEndpoint or TargetEndpoint
Name The unique name of the Flow. N/A Yes
Condition A conditional statement that evaluates on or more variables to evaluate to true or false. All Flows other than the predefined PreFlow and PostFlow types must define a condition for their execution. N/A Yes
Request The pipeline associated with Request message processing N/A No
Response The pipeline associated with Response message processing N/A No

Step processing

The sequential ordering of conditional Flows is enforced by Apigee Edge. Conditional Flows execute from top to bottom. The first conditional Flow whose condition evaluates to true is executed, and only one conditional Flow is executed.

For example, in the following Flow configuration, any inbound request that does not include the path suffix /first or /second will cause the ThirdFlow to execute, enforcing the policy called Return404.

<Flows>
  <Flow name="FirstFlow">
    <Condition>proxy.pathsuffix MatchesPath "/first"</Condition>
    <Request>
      <Step><Name>FirstPolicy</Name></Step>
    </Request>
  </Flow>
  <Flow name="SecondFlow">
    <Condition>proxy.pathsuffix MatchesPath "/second"</Condition>
    <Request>
      <Step><Name>FirstPolicy</Name></Step>
      <Step><Name>SecondPolicy</Name></Step>
    </Request>
  </Flow>
  <Flow name="ThirdFlow">
    <Request>
      <Step><Name>Return404</Name></Step>
    </Request>
  </Flow>
</Flows>

A note on 'API resources'

A common usage of conditional flows is the definition of 'API resources', as defined by the WADL specification.

Warning 'API resources' should not be confused with 'proxy resources'. An API resource uses the definition from the web application definition language (WADL) specification to identify specific RESTful 'resources'. Proxy resources (defined below) define code, scripts, or other files that can be attached to API proxy flows by referencing them in policies.

When an API resource is created in the Management UI, a conditional flow for the URI is configured in the API proxy.

A sample API resource configuration:

<Flow name="MyAPIResource">
  <Condition>proxy.pathsuffix == "/api_resource"</Condition>
  <Request>
	<Step><Name>ApiResource</Name></Step>
  </Request>
</Flow>

By defining API resources this way you gain the ability to:

  • Apply policies to individual URIs
  • Obtain operational metrics on specific URIs
  • Bundle specific URIs in API policies

Resources

"Resources" are scripts, code, and XSL transformations that can be attached to Flows using policies.

Four resource types are supported:

  • Compiled JavaScript: Stored under the /jsc directory
  • Python scripts: Stored under the /py directory
  • Java classes (packaged as JAR files): Stored under the /java directory
  • XSL transformations: Stored under the /xsl directory

Resources can be stored in an API proxy, an environment, or an organization. In each case, a resource is referenced by name in a Policy. API Services resolves the name by moving from the API proxy, to environment to organization level.

A resource stored at the organization level can be referenced by Policies in any environment. A resource stored at the environment level can be referenced by Policies in that environment. A resource stored at the API proxy level can be referenced only by Policies in that API proxy.

Post questions to the Apigee Developer Forum.

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?)