WSO2 APIM: Dynamic endpoint URLs

4 months ago · 5 min read


In this post, I will be discussing, how to change the API endpoint URL dynamically when you are moving an API through different environments in WSO2 API Manager. A good use case on, when we need to change the endpoint URL dynamically has been explained in this post by Nuwan. In a scenario where you have different unique endpoint per each environment and you need to change the endpoint URL in the API in all the time, you transfer an API from one environment to the other. This would be a painstaking task if you are transferring multiple APIs at once. As a solution for this, in the above article, it has suggested a method using a custom class mediator and an addition of new sequence to APIM deployment.I had followed it when I'm looking for a way to change the endpoint URL dynamically. It is still working perfectly, but it seems out of date now. In this post, I will be discussing a new method to change the endpoint URL dynamically. The new method would be slightly different from the method described in above post so I would suggest you go through the previous post before trying out the new method.

How Its Works

Because with the introduction of system scope[2] in Synapse get-property function, now you can directly get the system property values to synapse context by using get-property('system','property_name')  method.So it is much easier that writing class mediator and put it into repository/components/lib/  directory. In this method, I will be using the get-property synapse function instead of adding custom class mediator to the sequence (<class name="org.wso2.carbon.env.EnvironmentResolver"/> ). What this synapse function does is, It calls the underline Java System.getProperty(key); method[3] when we use the get property function with 'system' scope. So that we can get the environment variables which we have defined in the shell.We can define an environment variable to hold any value which we need to fill with the placeholders defined in the Endpoint URLs. During the runtime, we get those values in environment variables and update the endpoint URLs before sending the API request to its endpoints.


Setting up

We can define the environment variable as follows using the command arguments
./bin/ -Denvironment.port=8080
In the above example, names of the environment variables are host and port which are coming after -Denvironment. segment. You can define any number of a variable like this and refer them inside the sequence as below.Below is a sample synapse sequence, which assigns values to synapse properties by getting them from get-property function. This is the only file you need to add to the APIM setup in order to get the dynamic endpoint URL function to work.You have to add this in_sequence.xml file into repository/deployment/server/synapse-configs/default/sequences/ directory.

How the synapse property and placeholder values in the endpoint URL mapped?. It works like this. You can define an HTTP/REST Endpoint URL as http://{uri.var.sub_domain1}{uri.var.port}/apis/ in this example I have use two placeholder values which are  {uri.var.subdomain1} and {uri.var.port} you don't need to match these names with the environment variables defined in the previous step( The name should follow the pattern of {uri.var.anyvariablename}. We have referred the name inside the curly brackets(uri.var.anyvariablename) in our sequence file before. uri.var. segment identifies the string as part of HTTP endpoint URL.

apim pub dynamic endpoints

Here is an example which I have setup in sample API definition through WSO2 APIM publisher application. Once you have defined the endpoint URL as mentioned above and put that synapse sequence file into all your deployments. You can start the server in each environment with the relevant subdomain value for each environment. So that when you transfer you API from one environment to another, You don't need to change the endpoint your all the time.

For an example, you can start your DEV, QA, PROD deployments as follows,

./bin/ -Denvironment.port=8080
./bin/ -Denvironment.port=8081
./bin/ -Denvironment.port=80

the respective endpoint URLs would be

These endpoint URLs will be resolved in the runtime, at the time APIM receive an API call to its endpoint.

[1] :

[2] :

[3] :