API proxy configuration reference

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

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.

The most common ways to edit proxy configurations are:

• Using the XML editor within the Edge UI
• Download the configuration and edit it locally, as described in Local development of proxy configurations.

Local development of proxy configurations

You can download your proxy configurations so that you can edit them on a local machine. When you're done, you then upload the results to Edge. This approach lets you integrate the proxy configurations into your source control, versioning, and other shared workflows. In addition, by working on a proxy configuration locally, you can use your own XML editor and validation tools.

This section describes how to use the UI to download an existing proxy confuration, edit it, and then upload it back to Edge for deployment. You can also use apigeetool to download and deploy a new proxy configuration (by using the fetchproxy and deployproxy commands, respectively.)

To edit a proxy configuration locally using the UI:

1. Download the current proxy configuration in the Edge UI. (In the API Proxies view, select Project > Download Revision.)
2. On your local machine, create a new directory and expand the downloaded ZIP file into it.

   To expand the ZIP file, you can use a utility such as unzip, as the following example shows:

   mkdir myappdir
   unzip ./my-app_app_rev3_2019_04_20.zip -d myappdir

   The expanded contents of the ZIP file should be similar to the structure described in API proxy structure.

3. Edit the source files as necessary. For a description of the source files in a proxy configuration, see Configuration files and directory structure of an API proxy.

   For example, to enable health monitoring in your API proxy, edit the TargetEndpoint configuration file in the /apiproxy/targets/ directory. The default file in this directory is default.xml, although there might be files with different names if you use conditional targets.

   In this case, if the TargetEndpoint configuration file and its directory do not exist, create them.

4. After you finish editing the proxy configuration files, be sure to save your changes.
5. Change to the new directory that you created when you expanded the ZIP files (the root of the expanded configuration files).

   For example, if you expanded the files into the /myappdir directory, change to that directory, as the following example shows:

   cd myappdir

   You should change to this directory before you re-archive your proxy configuration files because you do not want the /myappdir directory to be included in the ZIP file. The top-level directory in the ZIP file must be /apiproxy.

6. Re-archive the proxy configuration files, including the new or changed files. You can use a utility such as zip, as the following example shows:

   zip my-new-proxy.zip -r .

   The top-level directory in the ZIP file must be /apiproxy.

   There are no special requirements for the ZIP file name. For example, you do not need to increment the revision number or specify the date in the file name, but doing this can be useful for debugging or source control.

   Edge increments the revision number of the new proxy configuration for you when you upload it.

7. Upload the new proxy configuration using the Edge UI. (In the API Proxies view, select Project > Upload a New Revision.)

   If you get an error such as Bundle is invalid. Empty bundle., then make sure your ZIP file's top-level directory is /apiproxy. If it isn't, re-archive your proxy configuration files from the root of the expanded directory.

   After uploading your new proxy configuration, Edge increments the revision number and displays it in the Revision Summary view.

   Edge does not deploy the new revision for you after you upload it with the UI.

8. Deploy your new revision.

For more information see Tutorial: How to download a proxy using the UI and the management API in the Apigee Community.

API proxy structure

An API proxy consists of the following configuration:

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
• ProxyEndpoint
• TargetEndpoint
  • TLS/SSL TargetEndpoint Configuration
• Policies
• Flows
• Resources

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

ProxyEndpoint

The following image shows the request/response flow:

/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">
  <PreFlow/>
  <Flows/>
  <PostFlow/>
  <HTTPProxyConnection>
    <BasePath>/weather</BasePath>
    <VirtualHost>default</VirtualHost>
  </HTTPProxyConnection>
  <FaultRules/>
  <DefaultFaultRule/>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

The required configuration elements in a basic ProxyEndpoint are:

ProxyEndpoint Configuration Elements

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

A TargetEndpoint is the outbound equivalent of a ProxyEndpoint. A TargetEndpoint functions as client to a backend service or API -- it sends requests and receives responses.

An API proxy needn't have any 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 another service or resource.

Here's a sample TargetEndpoint configuration:

<TargetEndpoint name="default">
  <PreFlow/>
  <Flows/>
  <PostFlow/>
  <HTTPTargetConnection>
    <URL>http://mocktarget.apigee.net</URL>
    <SSLInfo/>
  </HTTPTargetConnection>
  <FaultRules/>
  <DefaultFaultRule/>
  <ScriptTarget/>
  <LocalTargetConnection/>
</TargetEndpoint>

TargetEndpoint Configuration Elements

A TargetEndpoint can call a target in one of the following ways:

• HTTPTargetConnection for HTTP(S) calls
• LocalTargetConnection for local proxy-to-proxy chaining
• ScriptTarget for calls to an Edge-hosted Node.js script

Configure only one of these in a TargetEndpoint.

TLS/SSL TargetEndpoint Configuration

TargetEndpoints often need to manage HTTPS connections with heterogeneous backend infrastructure. For this reason, a number of TLS/SSL configuration settings are supported.

TLS/SSL TargetEndpoint Configuration Elements

<Ciphers>
 <Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher>    
 <Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher>
</Ciphers>

<Protocols>
 <Protocol>TLSv1.1</Protocol>
 <Protocol>TLSv1.2</Protocol>
</Protocols>

<CommonName wildcardMatch="true">*.myhost.com</CommonName>

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, see Configuring TLS from Edge to the backend (Cloud and Private Cloud).

Using flow variables to set TLS/SSL values dynamically

You can also dynamically set TLS/SSL details to support flexible runtime requirements. For example, if your proxy connects to two potentially different targets (a test target and a production target), you can have your API proxy programmatically detect which environment it's calling and dynamically set references to the appropriate keystore and truststore. The following Apigee Community article explains this scenario in more detail and provides deployable API proxy examples: https://community.apigee.com/articles/21424/dynamic-sslinfo-for-targetendpoint-using-variable.html.

In the following example of how the <SSLInfo> tag would be set in a TargetEndpoint configuration, the values can be supplied at runtime, for example, by a Java Callout, a JavaScript policy, or an Assign Message policy. Use whichever message variables contain the values you want to set.

Variables are allowed in only the following elements.

<SSLInfo>
    <Enabled>{myvars.ssl.enabled}</Enabled>
    <ClientAuthEnabled>{myvars.ssl.client.auth.enabled}</ClientAuthEnabled>
    <KeyStore>{myvars.ssl.keystore}</KeyStore>
    <KeyAlias>{myvars.ssl.keyAlias}</KeyAlias>
    <TrustStore>{myvars.ssl.trustStore}</TrustStore>
</SSLInfo>

Using references to set TLS/SSL values dynamically

When configuring a TargetEndpoint that uses HTTPS, you have to consider the case when the TLS/SSL cert expires, or a change to the system configuration requires you to update the cert. In an Edge for Private Cloud installation, when configuring TLS/SSL by using static values or by using flow variables, there is a chance that you will have to restart the Message Processors.

For more, see Update a TLS certificate.

However, you can optionally configure the TargetEndpoint to use a reference to the keystore or truststore instead. The advantage to using a reference is that you can update the reference to point to a different keystore or truststore to update the TLS/SSL cert without having to restart Message Processors.

For example, shown below is a TargetEndpoint that uses a reference to the keystore:

<SSLInfo> 
    <Enabled>true</Enabled> 
    <ClientAuthEnabled>false</ClientAuthEnabled> 
    <KeyStore>ref://keystoreref</KeyStore> 
    <KeyAlias>myKeyAlias</KeyAlias> 
</SSLInfo>

Use the following POST API call to create the reference named keystoreref:

curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
-d '<ResourceReference name="keystoreref">
    <Refers>myTestKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
</ResourceReference>' -u email:password

The reference specifies the name of the keystore and its type.

Use the following GET API call to view the reference:

curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password

To later change the reference to point to a different keystore, ensuring that the alias has the same name, use the following PUT call:

curl -X PUT -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references/keystoreref \
-d '<ResourceReference name="keystoreref">
    <Refers>myNewKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
</ResourceReference>' -u email:password

TargetEndpoint with target load balancing

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

For detailed instructions, refer to Load balancing across 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

Policy Attachment

The following image shows the API proxy flows execution sequence:

As shown above:

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

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' flows, and a PostFlow.

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

Additionally, you can add a PostClientFlow to the ProxyEndpoint, which executes after the response is returned to the requesting client app. Only the MessageLogging policy and the Google Stackdriver Logging Extension can be attached to this flow. PostClientFlow reduces API proxy latency and makes information available for logging that is not calculated until after the response is returned to the client, such as the client.sent.start.timestamp and client.sent.end.timestamp.The flow is used primarily for measuring the time interval between the start and end timestamps for the response message.

Watch a quick how-to video

Here's an example of a PostClientFlow with a message logging policy attached.

    ...
    <PostFlow name="PostFlow">
        <Request/>
        <Response/>
    </PostFlow>
    <PostClientFlow>
        <Request/>
        <Response>
            <Step>
                <Name>Message-Logging-1</Name>
            </Step>
        </Response>
    </PostClientFlow>
    ...

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').

The API proxy tests for the condition specified in the conditional flow and, if the condition is met, the processing steps in the conditional flow are executed by the API proxy. If the condition is not met, then the processing steps in the conditional flow are bypassed. Conditional flows are evaluated in the order defined in the API proxy and the first one whose condition is met is executed.

By defining conditional flows, you gain the ability to apply processing steps in an API proxy based on:

• Request URI
• HTTP verb (GET/PUT/POST/DELETE)
• Value of a query param, header, and form param
• Many other types of conditions

For example, the following conditional flow specifies that it is executed only when the request resource path is /accesstoken. Any inbound request with the path /accesstoken causes this flow to be executed, along with any policies that are attached to the flow. If the request path does not include the 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> 
  </Flow>
</Flows>   

Flow Configuration Elements

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>

Resources

"Resources" (resource files for use in API proxies) are scripts, code, and XSL transformations that can be attached to Flows using policies. These appear in the "Scripts" section of the API proxy editor in the management UI.

See Resource files for the supported resource types.

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.