Chaining API proxies together

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

You can specify that one proxy is the target endpoint of another, effectively connecting the two proxies in a proxy chain. Chaining proxies in this way can help you avoid a network hop, and so improve overall performance.

With proxy chaining, you specify that one proxy is the local target endpoint of the other. Rather than using the HTTPTargetConnection element to make a call to the second proxy, you use the LocalTargetConnection element.

<LocalTargetConnection>
    <APIProxy>myproxy2</APIProxy>
    <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>

You might find proxy chaining useful when you have a proxy that offers some discrete low-level functionality that other proxies will consume. For example, a proxy that exposes create/read/update/delete operations with a backend data store could be the target proxy for multiple other proxies that expose the data to clients.

Video: Watch a short video to learn more about API proxy chaining.

How proxy chaining works

Proxy chaining uses a local connection to minimize network overhead when calling one proxy from another. This local connection is more efficient because it bypasses network features such as load balancers, routers, and message processors.

The following illustrates the difference between connecting proxies with HTTPTargetConnection and LocalTargetConnection (proxy chaining):

Diagram of proxy-to-proxy call without proxy chaining.

Diagram of proxy-to-proxy call with proxy chaining.

You connect proxies by specifying that one is a local target endpoint of the other. For the configuration in the diagram above (Proxy-to-proxy call with proxy chaining), you would specify that ProxyB (/proxyB) is a local target endpoint of ProxyA (/proxyA). This causes requests arriving at ProxyA to be forwarded to ProxyB.

You can create a local connection between proxies in two ways:

  • By specifying the name of the target proxy and a ProxyEndpoint name
  • By specifying a path to the target proxy endpoint

You connect target proxies within a TargetEndpoint configuration, using a LocalTargetConnection element, as described below.

Connecting proxies by proxy name

You can specify the target proxy by name. You might find that this is most useful when you're creating the connection from the start and developing the proxies together. If you don't know the name (or the name might change), consider connecting with the target proxy's endpoint path, as described below.

When you connect to a target proxy by name, you specify the proxy's name and the name of its ProxyEndpoint.

The following example specifies a target proxy called data-manager, along with the ProxyEndpoint name exposed by data-manager. For reference information, see API proxy configuration reference.

<TargetEndpoint name="datamanager">
    <PreFlow name="PreFlow">
        <!-- PreFlow policies -->
    </PreFlow>
    <PostFlow name="PostFlow">
        <!-- PostFlow policies -->
    </PostFlow>
    <LocalTargetConnection>
        <APIProxy>data-manager</APIProxy>
        <ProxyEndpoint>default</ProxyEndpoint>
    </LocalTargetConnection>
</TargetEndpoint>

Connecting proxies by path

You can specify the target proxy by its endpoint path. You might want to do it this way when you don't know the proxy name, or when the name might change.

If your proxy is simply the consumer of the target proxy—such as when you're not developing both—the path might be the most reliable way to connect. For example, if the proxy you're connecting to is developed and maintained by another team, you might want to connect using a reliable endpoint path.

The following example specifies a target proxy at /v1/streetcarts/foodcarts/data-manager, where the host is assumed to be the same as the current proxy. For reference information, see API proxy configuration reference.

<TargetEndpoint name="datamanager">
    <PreFlow name="PreFlow">
        <!-- PreFlow policies -->
    </PreFlow>
    <PostFlow name="PostFlow">
        <!-- PostFlow policies -->
    </PostFlow>
    <LocalTargetConnection>
        <Path>/v1/streetcarts/foodcarts/data-manager</Path>
    </LocalTargetConnection>
</TargetEndpoint>

The <Path> element under <LocalTargetConnection> can be a string, or you can use a message template to assign a value dynamically.

Connecting proxies using the Apigee UI

You can also connect proxies, either by proxy name or path, using the Apigee UI. In the following example, there are two proxies, ProxyA and ProxyB, and you want ProxyB to be a target endpoint of ProxyA. To connect the proxies by proxy name, do the following steps:

  1. Sign in to the Apigee UI.
  2. Select Develop > Proxies in the left-hand pane.
  3. In the list of proxies, select ProxyA.
  4. Click the Develop tab.
  5. In the Code pane, replace the <TargetEndpoint> section of the XML with the following:
    <TargetEndpoint>
      <LocalTargetConnection>
        <APIProxy>ProxyB</APIProxy>
        <ProxyEndpoint>default</ProxyEndpoint>
      </LocalTargetConnection>
    </TargetEndpoint>
  6. Click Save.

Chained proxies, API products, and security

Proxy chaining is best for cases where both proxies are in the same API product. By default, both are available to clients. Apigee currently doesn't support bundling the second proxy in a separate API product that clients shouldn't have access to.

If your second proxy must be secured against direct client requests, consider adding logic to have your second proxy examine the IP address of the client. In the case of a call made with chaining, the IP address will be local. Your code can validate that it is local before allowing processing to continue. See the AccessControl policy for one way to do this.