How to map your API version using DLB?

Last Updated on 30/05/2021 by Patryk Bandurski

In the last article, I described two scenarios of API versioning for the CloudHub environment. I recommended embedding the API version in the application name to allow easily deploying multiple versions of the API at the same time. Did you know that we can even improve that approach? We can use a feature of Dedicated Load Balancer called URL mapping rules.

Mapping API version using DLB

Down below, you can see a high-level overview. The consumer is reaching our API via Dedicated Load Balancer. The URL consists of DLB hostname and pattern allowed on DLB’s URL mapping rules. The consumer provides a version like in any ordinary API, for instance,*. In the diagram, the version is replaced with the placeholder by any value. DLB maps input URI into the target application name and path to invoke depending on the value provided. For the presented example, it can be*. The URL mapping rules are very powerful and useful for our scenario. Let’s see some details.

URL mapping rule translating version from the base path into the application name

URL mapping rules

How URL mapping rules works?

A single URL mapping rule consits of

  • Input Path: path after the DLB hostname,
  • Target App: target application name,
  • Output Path: URI to be called on the target application,
  • Protocol: target protocol handled by our application like HTTP, HTTPS, WS, or WSS.

Take a look at the diagram below. It depicts parts described above on the actual URL accessible via DLB and the target application URL.

URL mapping rules parts depicated on examle DLB URL and target application URL

Input Path, Target App, and Output Path accept placeholders for generating patterns for services. This is a convenient feature, as we do not need to generate new rules every time a new application arrives. We can define a placeholder that the engine will match and replace in Target App and Output Path.

Add new URL mapping rule

Once you opened the DLB details window, you can go to the URL Mapping Rules section. In our scenario, we would like to map /portal/api/v1 and /portal/api/v2 into respectively myproject-portal-eapi-v1 and myproject-portal-eapi-v2. So we start by defining the Input Path pattern. In my opinion, it should look as follows:


The app placeholder is for values like a “portal“, and the version placeholder is for values like “v1“, “v2″ etc. Of course, you can pick different placeholder names. You define them. It just must be readable!

Okay, as we have Input Path, it is time to define Target App. To define it, we use placeholders from the Input Path. In my case it should looks like


It is plain and simple, we concatenate the placeholders’ values, and as a result, we receive the target application name. For instance myproject-portal-eapi-v1. How about the Output Path? Usually, you would leave the default value – slash character. However, in our case, it needs to be /api/.

Why do we need /api/? By default, your HTTP Listener base path is set to /api/*. If you take a close look at the Input Path, you will notice that /api/ is part of the input pattern and won’t be translated into the output path, so we need to add it. Otherwise, we would call myproject-portal-eapi-v1/*.

URL Mapping Rule appending version into the application name
URL Mapping Rule appending version into the application name

Down below I put a screenshot from Postman with my test call. As you can see, the URI does not contain the application name. Based on the mapping rule defined above, traffic is routed to myproject-portal-eapi-v2 application.

Testing API call via Dedicated Load Balancer
Testing API call via Dedicated Load Balancer


Dedicated Load Balancer is a very powerful Anypoint Platform component. Using its URL Mapping Rules, we can construct very flexible URI patterns that map incoming URI into the application names. Today’s topic was hiding the API version from the application name. We achieved this using the aforementioned URL Mapping Rules. Consequently, consumers received friendlier URIs to call where the API version is part of the base URI.

How to map your API version using DLB?

Leave a Reply

Your email address will not be published. Required fields are marked *

Scroll to top