Configure base path routing

This topic discusses base path routing. Base path routing allows you to configure and manage how Apigee hybrid routes API proxy calls to the correct environment.

Use base path routing to manage proxy deployments

Because you can map a single virtual host to multiple environments in hybrid, you need a way to specify which proxy base path maps to which environment.

For example, let's say you want to map two environments to the same host alias: apitest.mydomain.net. In your overrides file, you could create the following configuration where environments dev1 and dev2 both map to this host. For example:

envs:
  - name: dev1
    hostAlias: "apitest.mydomain.net"
    ...
  - name: dev2
    hostAlias: "apitest.mydomain.net"
    ...

Now, let's say you deploy proxies to these environments. You deploy:

  • Proxy foo1 with base path /foo1 to dev1
  • Proxy foo2 with base path /foo2 to dev2

Suppose a client calls this API: https://apitest.mydomain.net/foo1. Note there's nothing in this path (or in the host header that's generated for the request) that tells hybrid which environment to route the call to. Is the foo1 proxy deployed to dev1 or dev2? Based only on the request URL, there's no way to tell. You must explicitly map each of these base paths to one or more environments.

To specify which environment a proxy call should be routed to, add the paths.uri.prefixes property to the envs property in your overrides file, as shown in the following example:

envs:
  - name: dev1
    hostAlias: "apitest.mydomain.net"
    paths:
      uri:
        prefixes:
        - /foo1
    ...
  - name: dev2
    hostAlias: "apitest.mydomain.net"
    paths:
      uri:
        prefixes:
        - /foo2
    ...

Now, when an API call comes in such as: https://apitest.mydomain.net/foo1, the ingress router knows where to send it. It knows that the /foo1 proxy is deployed to the dev1 environment, and the call gets routed to dev1's message processor.

If you send this call, https://apitest.mydomain.net/foo2, it is likewise routed to the dev2 environment's MP, and so on.

In summary, the paths.uri.prefixes configuration lets you manage proxy deployments among multiple environments that share the same host alias.

Best Practice: Use base path routing when you want multiple environments to share the same host alias. Base path routing lets you limit the number of proxies deployed to any single environment.

The next section explains in more detail why it's a good idea to limit the number of proxies deployed to an environment and helps guide you in deciding how to manage your proxy deployments.

Deploy a new proxy in a multi-environment configuration

After you create a new proxy, you can deploy it to one or more environments. If you have multiple environments that share the same host alias, then you must use base path routing to tell hybrid explicitly which environment to route the proxy to.

For example, if you create a new proxy with the base path /foo4, and you want to deploy it to the environment called dev1, then add this configuration to your overrides:

envs:
  - name: dev1
    hostAlias: "apitest.mydomain.net"
    ...
    paths:
      uri:
        prefixes:
        - /foo1
        - /foo4
  - name: dev2
    hostAlias: "apitest.mydomain.net"
    ...
    paths:
      uri:
        prefixes:
        - /foo2

Now, if an API call comes in for https://apitest.mydomain.net/foo4, hybrid knows to route it to environment dev1.