API proxy configuration reference

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

As a developer working with Apigee, 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 Building a simple API proxy.

Edit your API proxy configuration using one of the following methods:

• Use the Apigee UI or API.
• Download the API proxy configuration bundle, edit it manually, and upload the new configuration to Apigee, as described in Downloading and uploading an API proxy configuration bundle.

API proxy configuration directory structure

The API proxy configuration directory structure is shown below:

An API proxy configuration consists of the following contents:

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

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-Za-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 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 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 Apigee 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 Apigee 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 proxy endpoints in the /proxies directory of this API proxy. You will normally only see this element when the API proxy was created using the Apigee 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 Apigee UI. This is simply a manifest setting, designed to provide visibility into the contents of the API proxy.	N/A	No
Spec	Identifies the OpenAPI Specification that is associated with the API proxy. The value is set to a URL or to a path in the specification store.	N/A	No
TargetServers	A list of target servers referenced in any target endpoints of this API proxy. You will normally only see this element when the API proxy was created using Apigee. This is simply a manifest setting, designed to provide visibility into the contents of the API proxy.	N/A	No
TargetEndpoints	A list of target endpoints in the /targets directory of this API proxy. You will normally only see this element when the API proxy was created using the Apigee UI. This is simply a manifest setting, designed to provide visibility into the contents of the API proxy.	N/A	No

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 proxy endpoint, 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>
    <Properties/>
  </HTTPProxyConnection>
  <FaultRules/>
  <DefaultFaultRule/>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

The required configuration elements in a basic proxy endpoint are:

ProxyEndpoint configuration elements

Name	Description	Default	Required?
ProxyEndpoint
name	The name of the proxy endpoint. Must be unique within the API proxy configuration, when (in rare cases) multiple proxy endpoints are defined. The characters you are allowed to use in the name are restricted to the following: A-Za-z0-9._\-$ %.	N/A	Yes
PreFlow	Defines the policies in the PreFlow flow of a request or response.	N/A	Yes
Flows	Defines the policies in the conditional flows of a request or response.	N/A	Yes
PostFlow	Defines the policies in the PostFlow flow of a request or response.	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 to route incoming messages to the proper API proxy. The BasePath is a URI fragment (for example /weather) appended to the base URL of an API proxy (for example, http://apifactory-test.apigee.net). BasePath must be unique within an environment. Uniqueness is validated when an API proxy is generated or imported. Using a wildcard in base paths You can use one or more "*" wildcards in API proxy base paths. For example, a base path of /team/*/members allows clients to call https://[host]/team/blue/members and https://[host]/team/green/members without you needing to create new API proxies to support new teams. Note that /**/ is not supported. Important: Apigee does NOT support using a wildcard "*" as the first element of a base path. For example, this is NOT supported: /*/search. Starting the base path with a "*" can lead to unexpected errors because of the way Apigee identifies valid paths.	/	Yes
Properties	A set of optional HTTP configuration settings can be defined as properties of a <ProxyEndpoint>. Use the property request.queryparams.ignore.content.type.charset to tell the proxy to ignore the charset parameter of the Content-Type header when processing the request URL. For example: <Property name= \ "request.queryparams.ignore.content.type.charset">true</> The following table shows example output depending on the setting of the charset property and presence of the Content-Type header's charset parameter. Property setting Header value Example output charset=false charset param not set [e-mail] charset=false charset=utf-8 john.doe [e-mail] charset=true and no charset param in header. charset param not set [e-mail] charset=true charset=utf-8 param set [e-mail]	N/A	No
FaultRules	Defines how the proxy endpoint reacts to an error. A fault rule specifies two items: A Condition that specifies the fault to be handled based on the pre-defined category, subcategory, or name of the fault One or more policies that define the behavior of the fault rule for the corresponding Condition See Handling faults.	N/A	No
DefaultFaultRule	Handles any errors (system, transport, messaging or policy) that are not explicitly handled by another fault rule. See Handling faults.	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 target endpoint, an IntegrationEndpoint, or an 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-Za-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 target endpoint is any target endpoint defined in the same API proxy under the/targets directory). By naming a target endpoint, you indicate where request messages should be forwarded after processing by the ProxyEndpoint request pipeline. Note that this is an optional setting. A proxy endpoint 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 target endpoint, 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 proxy endpoint, bypassing any TargetEndpoint configurations that might be stored under /targets	N/A	No

How to configure RouteRules

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

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

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

Direct URL invocation

A proxy endpoint can also directly invoke a backend service. Direct URL invocation bypasses any named TargetEndpoint configuration under /apiproxy/targets). For this reason, TargetEndpoint is an optional API proxy configuration, although, in practice, direct invocation from the proxy endpoint 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. See Conditions reference and Flow 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 target endpoint 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>

Note: More dynamic routing

The Apigee community article specifying proxy endpoint shows dynamic routing to different world regions based on variables extracted from the request URI.

Null routes

A null RouteRule can be defined to support scenarios in which the request message does not need to be forwarded to the target endpoint. This is useful when the proxy endpoint performs all of the necessary processing, for example by using JavaScript to call an external service or retrieving data from a lookup to the Apigee 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 target endpoint is the outbound equivalent of a proxy endpoint. A target endpoint functions as client to a backend service or API—it sends requests and receives responses.

An API proxy needn't have any target endpoints. Proxy endpoints can be configured to call URLs directly. An API proxy with no target endpoints usually contains a proxy endpoint 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 target endpoint defines the outbound connection from Apigee 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/>
    <Authentication/>
  </HTTPTargetConnection>
  <FaultRules/>
  <DefaultFaultRule/>
  <ScriptTarget/>
  <LocalTargetConnection/>
</TargetEndpoint>

TargetEndpoint configuration elements

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

• HTTPTargetConnection for HTTP or HTTPS calls
• LocalTargetConnection for local proxy-to-proxy chaining

Configure only one of these in a target endpoint.

Name	Description	Default	Required?
TargetEndpoint
name	The name of the target endpoint, which must be unique within the API proxy configuration. The name of the target endpoint 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-Za-z0-9._\-$ %.	N/A	Yes
PreFlow	Defines the policies in the PreFlow flow of a request or response.	N/A	Yes
Flows	Defines the policies in the conditional flows of a request or response.	N/A	Yes
PostFlow	Defines the policies in the PostFlow flow of a request or response.	N/A	Yes
HTTPTargetConnection	With its child elements, specifies a backend resource reached via HTTP. If you use HTTPTargetConnection, don't configure other types of target connections (ScriptTarget or LocalTargetConnection). Note: The <LocalTargetConnection> elements support the dynamic string substitution feature called message templating. You can use the <Authentication> child element to make authenticated calls to Google services or custom services running on certain Google Cloud products, such as Cloud Functions and Cloud Run. Use of the <Authentication> element requires setup and deployment steps described in Using Google authentication. With proper setup, the policy creates an authentication token for you and adds it to the service request. See also <Authentication> element usage.
URL	Defines the network address of the backend service to which the target endpoint 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 target servers to decouple API proxy configurations from concrete backend service endpoints URLs.	N/A	No
Properties	A set of optional HTTP configuration settings can be defined as properties of a <TargetEndpoint>.	N/A	No
SSLInfo	Optionally define TLS/SSL settings on a target endpoint to control the TLS/SSL connection between the API proxy and the target service. See TLS/SSL TargetEndpoint Configuration. Note: The <SSLInfo> element supports the dynamic string substitution feature called message templating.	N/A	No
LocalTargetConnection	With its child elements, specifies a resource to be reached locally, bypassing network characteristics such as load balancing and message processors. To specify the target resource, include either the APIProxy child element (with the ProxyEndpoint element) or the Path child element. For more information, see Chaining API proxies together. If you use LocalTargetConnection, don't configure other types of target connections (HTTPTargetConnection or ScriptTarget).
APIProxy	Specifies the name of an API proxy to use as a target for requests. The target proxy must be in the same organization and environment as the proxy sending requests. This is an alternative to using the Path element.	N/A	No
ProxyEndpoint	Used with APIProxy to specify the name of the target proxy's proxy endpoint.	N/A	No
Path	Specifies the endpoint path of an API proxy to use as a target for requests. The target proxy must be in the same organization and environment as the proxy sending requests. This is an alternative to using APIProxy.	N/A	No
FaultRules	Defines how the target endpoint reacts to an error. A fault rule specifies two items: A Condition that specifies the fault to be handled based on the pre-defined category, subcategory, or name of the fault One or more policies that define the behavior of the fault rule for the corresponding Condition See Handling faults.	N/A	No
DefaultFaultRule	Handles any errors (system, transport, messaging or policy) that are not explicitly handled by another FaultRule. See Handling faults.	N/A	No

<Authentication> element usage

The use of the <Authentication> element in <TargetEndpoint> is identical to the usage of the <Authentication> element in the ServiceCallout policy. In both <TargetEndpoint> and ServiceCallout, <Authentication> is a subelement of <HttpTargetConnection>. For details, see Authentication element in the ServiceCallout policy reference.

<Authentication> element error reference

If you are using the <Authentication> element, you can find possible error messages and troubleshooting tips for deployment and runtime errors in the Errors section of the ServiceCallout policy documentation.

<Authentication> element examples

The following example shows how to call a service deployed on Cloud Run as the target using the Authentication element to generate an OpenID Connect token needed to authenticate the call:

<TargetEndpoint name="TargetEndpoint-1">
  <HTTPTargetConnection>
      <Properties/>
      <URL>https://cloudrun-hostname.a.run.app/test</URL>
      <Authentication>
          <GoogleIDToken>
             <Audience>https://cloudrun-hostname.a.run.app/test</Audience>
          </GoogleIDToken>
     </Authentication>
  </HTTPTargetConnection>
</TargetEndpoint>

The following example shows how to call a TargetService that points to Cloud Run using the Authentication element to generate an OpenID Connect token needed to authenticate the call. The HeaderName element adds the generated bearer token to a header named X-Serverless-Authorization that is sent to the target system. The Authorization header, if present, is left unmodified and also sent in the request.

<TargetEndpoint name="TargetEndpoint-1">
   <HTTPTargetConnection>
     <Authentication>
        <HeaderName>X-Serverless-Authorization</HeaderName>
        <GoogleIDToken>
            <Audience ref="flow.variable.audience">https://cloudrun-hostname.a.run.app</Audience>
        </GoogleIDToken>
     </Authentication>
      <LoadBalancer>
         <Server name="cloud-run-target" />
      </LoadBalancer>
   </HTTPTargetConnection>
</TargetEndpoint>

The following example shows how to call a TargetService that points to the Google Secret Manager service. In this example, the GoogleAccessToken element is configured to generate a Google Auth Token to authenticate the target request:

<HTTPTargetConnection>
   <Authentication>
      <GoogleAccessToken>
        <Scopes>
          <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
        </Scopes>
      </GoogleAccessToken>
    </Authentication>
    <URL>
      https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id
    </URL>
</HTTPTargetConnection>

The following example shows how to automatically set the audience of the GoogleIDToken. When useTargetUrl is true and the referenced variable does not resolve to a valid variable, the URL of the target (excluding query params) is used as the audience. Suppose the request path is /foobar and the target server URL is https://xyz.com, the audience of the GoogleIDToken will automatically be set to https://xyz.com/foobar.

Apigee hybrid users: If you use Apigee hybrid, note that the useTargetUrl attribute is available in Apigee hybrid version 1.8 and later versions.

<TargetEndpoint name="TargetEndpoint-1">
  <HTTPTargetConnection>
    <Authentication>
      <GoogleIDToken>
        <Audience ref='myvariable' useTargetUrl="true"/>
      </GoogleIDToken>
    </Authentication>
    <LoadBalancer>
      <Server name="TS" />
    </LoadBalancer>
  </HTTPTargetConnection>
</TargetEndpoint>

TLS/SSL TargetEndpoint configuration

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

Note: TLS (Transport Layer Security) is the updated version of the now-deprecated SSL (Secure Sockets Layer) specification. Because Apigee originally supported SSL, you may see some instances in the Apigee UI and in the Apigee configuration elements that use the term SSL. However, Apigee uses TLS exclusively.

TLS/SSL TargetEndpoint configuration elements

Name	Description	Default	Required?
SSLInfo	The <SSLInfo> block can be used for both one-way and two-way TLS/SSL.
Enabled	When set to true, specifies that the target connection should use the SSL protocol in accordance with any other parameters specified in this <SSLInfo> block. When set to false, specifies that the target connection should not use SSL. However, if the enclosing <HTTPTargetConnection> block contains a <URL> element that evaluates to a string that begins with https://, then the SSL protocol will be used even if <Enabled> is false. In this case, the entire <SSLInfo> block is ignored. Conversely, if there is a <URL> element that begins with http://, then the SSL protocol will not be used even if <Enabled> is true.	false	No
Enforce	Enforces strict SSL between Apigee and the target backend. If set to true, connections will fail for targets with invalid certs, expired certs, self-signed certs, certs with a hostname mismatch, and certs with an untrusted root. A failure code of 4xx or 5xx is returned. If unset, or set to false, the result of connections to target backends with problematic certs depends upon the setting of <IgnoreValidationErrors> (see below). A success response (2xx) can occur under certain conditions, if <IgnoreValidationErrors> is set to true. You can override the Enforce field at the environment level with the feature flag SSLInfo.Enforce. See Specifying environment-level SSL enforcement.	false	No
TrustStore	A keystore containing trusted root server certificates. Apigee will treat the remote peer as trusted if the certificate chain it sends terminates in a certificate that is contained in this keystore.	N/A	No
ClientAuthEnabled	If set to true, enables two-way TLS (also known as mutual TLS or mTLS) between Apigee and the remote peer - either the API client, or the target backend. Enabling two-way TLS typically requires that you set up both a truststore and a keystore on Apigee.	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)
IgnoreValidationErrors	Indicates whether validation errors are ignored. If the backend system uses SNI and returns a cert with a subject Distinguished Name (DN) that does not match the hostname, there is no way to ignore the error and the connection fails. Note: If <Enforce> is set to true, the value of <IgnoreValidationErrors> is ignored.	false	No
Ciphers	Supported ciphers for outbound TLS/SSL. If no ciphers are specified, then all ciphers available for the JVM will be permitted. To restrict ciphers, add the following elements listing the supported ciphers: <Ciphers> <Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher> <Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher> </Ciphers>	N/A	No
Protocols	Supported protocols for outbound TLS/SSL. If no protocols are specified, then all protocols available for the JVM will be permitted. To restrict protocols, specify them explicitly. For example, to allow only TLS v1.2 or TLS v1.3: <Protocols> <Protocol>TLSv1.2</Protocol> <Protocol>TLSv1.3</Protocol> </Protocols>	N/A	No
CommonName	Apigee checks the value here against the CN (Common Name) or SANs (Subject Alternate Names) on the remote peer certificate.	N/A	No

Specifying environment-level SSL enforcement

If SSLInfo.Enforce is set to true or false, the value specified overrides any granular enforcement options specified in <SSLInfo> blocks in TargetEndpoint or TargetServer configurations.

If SSLInfo.Enforce is unset, SSL enforcement is determined by any values specified using the <Enforce> element within individual <SSLInfo> blocks. For more information, see TLS/SSL TargetEndpoint configuration.

In the following example, SSLInfo.Enforce is set to true. In the resulting output, you can see that SSL is enforced in the specified environment.

Note The API call in the example does not preserve the settings of any previously specified feature flags. In this call, you must re-specify any settings that you want to preserve.

VALUE=true
curl -Ss -v -X PUT \
    "https://apigee.googleapis.com/v1/organizations/MYORG/environments/MYENV" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer TOKEN" \
    -d '{
        "name": "MYENV",
        "properties": {
            "property": [{
                "name": "features.SSLInfo.Enforce",
                "value": "'"$VALUE"'"
            }]
        }
    }'
  

Output:

{
  ...
  "properties": {
    "property": [
      {
        "name": "features.SSLInfo.Enforce",
        "value": "true"
      }
    ]
  },
  ...
}

Sample target endpoint with outbound client authentication enabled

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

For detailed instructions, see Options for configuring TLS.

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 Dynamic SSLInfo for TargetEndpoint using variable reference Apigee Community article explains this scenario in more detail and provides deployable API proxy examples.

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 AssignMessage policy. Use whichever message variables contain the values you want to set.

Variables are allowed in only the following elements.

Note: These elements support the dynamic string substitution feature called message templating.

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

Note: Variable replacement of TLS/SSL values can only be used for a target endpoint. Any attempt to use variables in any other context, such as message logging, will cause validation failures.

Using references to set TLS/SSL values dynamically

When configuring a target endpoint 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.

For more information, see Handling expired certificates.

However, you can optionally configure the target endpoint 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.

Note: You can only use a reference to the keystore and truststore; you cannot use a reference to the alias. When you change the reference to a keystore, ensure that the alias name of the cert is the same as in the old keystore.

For example, shown below is a target endpoint 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 "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references" \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -d '<ResourceReference name="keystoreref">
    <Refers>myTestKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
</ResourceReference>'

Where $TOKEN is set to your OAuth 2.0 access token, as described in Obtaining an OAuth 2.0 access token. For information about the curl options used in this example, see Using curl. For a description of the environment variables used, see Setting environment variables for Apigee API requests.

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

Use the following GET API call to view the reference:

curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references/keystoreref" \
  -H "Authorization: Bearer $TOKEN"

Where $TOKEN is set to your OAuth 2.0 access token, as described in Obtaining an OAuth 2.0 access token. For information about the curl options used in this example, see Using curl. For a description of the environment variables used, see Setting environment variables for Apigee API requests.

curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references/keystoreref" \
  -H "Authorization: Bearer $TOKEN"

Where $TOKEN is set to your OAuth 2.0 access token, as described in Obtaining an OAuth 2.0 access token. For information about the curl options used in this example, see Using curl. For a description of the environment variables used, see Setting environment variables for Apigee API requests.

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 "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references/keystoreref" \
  -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -d '<ResourceReference name="keystoreref">
    <Refers>myNewKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
  </ResourceReference>'

Where $TOKEN is set to your OAuth 2.0 access token, as described in Obtaining an OAuth 2.0 access token. For information about the curl options used in this example, see Using curl. For a description of the environment variables used, see Setting environment variables for Apigee API requests.

TargetEndpoint with target load balancing

Target endpoints support load balancing across multiple named target servers using three load balancing algorithms.

For detailed instructions, refer to Load balancing across backend servers.

IntegrationEndpoint

An IntegrationEndpoint is a target endpoint that specifically runs Apigee integrations. If you have configured an IntegrationEndpoint, Apigee sends the request object to Apigee's Integration Platform for execution. To run your integration, in addition to configuring the IntegrationEndpoint, you must also add the SetIntegrationRequest policy in your proxy flow.

You can configure your integration to execute either synchronously or asynchronously by setting the <AsyncExecution> element in the IntegrationEndpoint configuration. For more information, see Synchronous vs Asynchronous execution. After running the integration, Apigee saves the response in the response message.

Note: You need an authentication token to run the IntegrationEndpoint. However, there is no explicit <Authentication> element in the IntegrationEndpoint definition. Apigee adds an authentication token to the request under the hood. For the IntegrationEndpoint to successfully authenticate, you must deploy your API proxy with a service account that has the required IAM roles to run an integration. For information about the required roles, see IAM roles for integrations. For more details on deploying an API proxy, see Deploy on Apigee.

Configuring IntegrationEndpoint

To configure an integration endpoint as your target endpoint, add the IntegrationEndpoint element to your ProxyEndpoint configuration. The following is a sample ProxyEndpoint configuration:

<ProxyEndpoint name="default">
    <Description/>
    <FaultRules/>
    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Name>my-set-integration-request-policy</Name>
            </Step>
        </Request>
    </PreFlow>
    <Flows/>
    <PostFlow name="PostFlow"/>
    <HTTPProxyConnection>
        <BasePath>/integration-endpoint-test</BasePath>
        <Properties/>
    </HTTPProxyConnection>
    <RouteRule name="default">
        <IntegrationEndpoint>my-int-endpoint</IntegrationEndpoint>
    </RouteRule>
</ProxyEndpoint>

In the sample ProxyEndpoint configuration, Apigee performs the following tasks:

1. In the PreFlow, executes the policy named my-set-integration-request-policy, which sets the integration request object and integration flow variables.
2. Uses my-int-endpoint as the target endpoint, as specified in the RouteRule.
3. Reads the integration request object created by the my-set-integration-request-policy.
4. Sends the request to Apigee's Integration Platform using the request object and flow variables set by the SetIntegrationRequest policy.
5. Saves the response of the integration in the response message.

The XML file containing the <IntegrationEndpoint> declaration will be available in the APIGEE_BUNDLE_DIRECTORY/apiproxy/integration-endpoints/ directory. If you create your API proxy using the Develop > API Proxies > CREATE NEW > Integration target option, Apigee stores the declaration in the /apiproxy/integration-endpoints/default.xml file. If you create the integration endpoint XML from the UI, you can provide a custom name for the XML file.

The following example shows the declaration of the <IntegrationEndpoint> element in the XML file:

<IntegrationEndpoint name="my-int-endpoint">
    <AsyncExecution>false</AsyncExecution>
</IntegrationEndpoint>

IntegrationEndpoint configuration elements

Name	Description	Default	Required?
IntegrationEndpoint
name	The name of the IntegrationEndpoint. The characters you can use in the name are restricted to: A-Za-z0-9._\-$ %	N/A	Yes
AsyncExecution	A Boolean value that specifies if the integration should run in synchronous or asynchronous mode. For more information, see Synchronous vs Asynchronous execution.	false	No

Synchronous vs Asynchronous execution

You can configure the integration to run in either synchronous or asynchronous mode. To understand the difference between synchronous and asynchronous execution modes, see <AsyncExecution>.

Use the <AsyncExecution> element within the </IntegrationEndpoint> to specify synchronous or asynchronous execution. If you set <AsyncExecution> to true, the integration runs asynchronously. And if you set it to false, the integration runs synchronously.

The following example sets the AsyncExecution to true:

<IntegrationEndpoint name="my-int-endpoint">
    <AsyncExecution>true</AsyncExecution>
</IntegrationEndpoint>

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
name	The internal name of the policy. Characters you can use in the name are restricted to: A-Za-z0-9._\-$ %. However, the Apigee UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric. Optionally, use the <DisplayName> element to label the policy in the Apigee UI proxy editor with a different, natural-language name.	N/A	Yes
enabled	Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.	true	No
continueOnError	Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails.	false	No
async	Note: This attribute does not make the policy execute asynchronously. In most cases, leave this with the default of false. When set to true, policy execution is offloaded to a different thread, leaving the main thread free to handle additional requests. When the offline processing is complete, the main thread comes back and finishes handling the message flow. In some cases, setting async to true improves API proxy performance. However, overusing async can hurt performance with too much thread switching. To use asynchronous behavior in API proxies, see JavaScript object model.	false	No

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

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 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 proxy endpoint, which executes after the response is returned to the requesting client app. Only the MessageLogging policy 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.

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

Proxy endpoints and target endpoints 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

Name	Description	Default	Required?
Flow	A request or response processing pipeline defined by a proxy endpoint or target endpoint
Name	The unique name of the Flow.	N/A	Yes
Condition	A conditional statement that evaluates one 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. However, if you include a single flow without a condition at the end of a sequence of flows, it will act as the "Else" statement at the end of the sequence of flows.	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. 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 Apigee UI.

See Managing resources 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. Apigee 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.