Skip to main content

Creating an API with a dynamically changing endpoint in API Cloud.


This blog explains how we can create a single API in the API Cloud and make it call multiple endpoints based on a version header passed in the request. Therefore we will not need to create an API per backend endpoint version and can use a custom sequence for the API to route to the required destination.


Pre requisite.

1. You need to make sure you have an account with the WSO2 Cloud. If you do not have an account then you first need to create one. You can find the steps here under 'How to create an Account with WSO2 Cloud'.

Lets see how we can configure the API cloud to carry out this requirement. 

In order to demonstrate the scenario i have used an endpoint of a service which is hosted in WSO2 App Cloud and have created two different versions [1] [2] of the endpoint and invoked accordingly by including this sequence to the API. I have used the default version as [1]. The versions are customerservice-default-SNAPSHOT and customerservice-1.1.0 respectively. Please refer the following steps in order to understand how you can add this functionality to your API.

First lets understand the custom sequence we need to create for this scenario. You can find the created sequence used from here.


1. Open up the custom in sequence xml file and make changes to it according to the guidelines provided below. I will mention the xml config here so you can configure it correctly. ( I have mentioned the instructions as comments.)

<sequence xmlns="http://ws.apache.org/ns/synapse" name="VersionManagerSequence">
<!-- Property name is the parameter name that we added as a parameter when defining the endpoint url -->
<!-- Property expression is how we will be retrieving the version passed as a header, i defined the header as Version when invoking using curl-->
<property name="uri.var.version" expression="get-property('transport','Version')"/>
<!-- Here we are checking if a header named as Version is available or not.-->
<filter source="boolean(get-property('uri.var.version'))" regex="false">
<then>
<!-- If no header mentioned as version is passed we will assign the version as our default version for the endpoint. So in the value you need to specify your default version of the endpoint -->
<property name="uri.var.version" value="customerservice-default-SNAPSHOT"/>
<then>
<else/>
</filter>
</sequence>


Make these changes and save your sequence.According to this customer sequence the curl request you will need to pass would be something similar to this

This is the sample curl request i used to test passing the endpoint version as customerservice-1.1.0.

curl -k -v -X GET --header "Accept: application/json" --header "Version: customerservice-1.1.0" --header "Authorization: Bearer access_token" "https://gateway.api.cloud.wso2.com/t/tenant/customer/1.0/customerservice/customers/123"


As you can see we are passing the version of the endpoint that we need as a header and the sequence will pick up that header value and assign it to the version parameter of our API endpoint.

Now lets see how we can correctly configure the API so that we can carry out the use case.


1. Log into the API Cloud and go to the publisher portal and select the Add option to add a new API.

2. Create the API as shown in the image below where the URI pattern needs to be customerservice/customers/{customerID} and select implement.


                       

3. Next when providing the Production/Sandbox endpoints, you need to specify it in a parameterized manner as below. Since i used the endpoint mentioned below it has to be specified as

http://appserver.dev.cloud.wso2.com/t/backstage/webapps/{uri.var.version}/services/customers/customerservice

4. After adding the endpoint you need to add the custom sequence we created. (VersionManagerSequence.xml).I have mentioned the parameter that would be changing dynamically based the header in the url in a parametric manner ( as {uri.var.version}) so that we can dynamically change the version using the sequence.



               




5. Next select the Manage button and in the Manage section add the needed throttling tiers and publish the API.

6. You need to then go to the API store and generate an access token for this API so that we can invoke this sample. You can find details about how to do this in the tutorial here

Then execute this curl command where we will be passing the version and the API will be directed to the respective version.


 curl -k -X GET --header 'Accept: application/json' --header "Version: customerservice-1.1.0" --header 'Authorization: Bearer <access_token>' 'https://gateway.api.cloud.wso2.com/t/mydemo/customerApp/1.0.0/customerservice/customers/123'

And you will receive a response as {"Customer":{"id":123,"name":"John"}}

If you do not pass the version header it will call to the default version we have set in the API. You can try that as well by calling using the following command.

curl -k -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <access_token>' 'https://gateway.api.cloud.wso2.com/t/mydemo/customerApp/1.0.0/customerservice/customers/123'


NOTE:

If you face an error where you are not able to invoke the backend when specifying the url in a parameterized manner. Add the keyword legacy-encoding at the start of the endpoint definition as shown below.

legacy-encoding:https://{uri.var.endpoint}


References:


[1] http://shenavid.blogspot.com/2015/10/wso2-cloud-wso2-cloud-consists-of-two.html
[2] https://docs.wso2.com/display/APICloud/Subscribe+to+and+Invoke+an+API.
[3] https://docs.wso2.com/display/APICloud/Change+the+Default+Mediation+Flow+of+API+Requests





Comments

Post a Comment

Popular posts from this blog

Processing large payloads with the esb script mediator iteratively

Overview WSO2 ESB uses Rhino engine to execute JavaScripts. Rhino engine converts the script to a method inside a Java class. Therefore, when processing large JSON data volumes, the code length must be less than 65536 characters, since the Script mediator converts the payload into a Java object. However, you can use the following alternative options to process large JSON data volumes. The script mediator which is used in ESB is powered by the Rhino engine. Therefore, when processing large JSON data volumes, the code length must be less than 65536 characters which is a limitation in the script mediator being used in the esb versions less than 5.0.0. In ESB 5.0.0 there is a higher capability to process larger payloads using script mediator. In order to process such large payloads we can follow the below two approaches. 1. Replace the javascript tranformation logic using java code by writing a custom mediator. [1] 2. Break down the large payload and execute them as sections using ...
Post a Comment
Read more

Invoking external endpoints using the call mediator in wso2 api manager

Introduction In API Manager if you need to do any service chaining use cases the call mediator comes in handy. If you need to use the response received by invoking one endpoint and then use it to invoke another endpoint you can use the call mediator in API Manager. The call mediator behaves in a synchronous manner. Hence, mediation pauses after the service invocation and resumes from the next mediator in the sequence when the response is received. You can read more about the call mediator in the wso2 esb documentation [1] . In api manager 1.10.0 the call mediator works in the blocking mode. Prerequisite Before we can use the call mediator in API Manager 1.10.0 we need to make the following changes to some configs. We need to comment the jms transport sender in axis2_blocking_client.xml found in the location APIM_HOME/repository/conf/axis2. This will resolve the jms sender initialization issues.   <!--transportSender name="jms"        ...
1 comment
Read more

Configure WSO2 Identity Server for single sign on with Moodle - Part I

Introduction Moodle is a learning platform designed to provide educators, administrators and learners with a single robust, secure and integrated system to create personalized learning environments.[1]. This is commonly used in the education sector and there might be occurrences where it would require to use SAML to login to Moodle instead of the default basic authentication. For this we would need to have an Identity Provider capable of issuing such SAML tokens and Moodle configured to accept the tokens in order to do the authentication I will be discussing this in two parts. Part I - How to configure moodle for SSO with WSO2 Identity Server Part II - How to carry our user provisioning and attribute profile mapping with Moodle and WSO2 Identity Server Let's see how this can be achieved using a SAML authentication plugin provided by one login. Prerequisite  You need to have a working version of Moodle installed. If you want to try this tutorial from scratch you can ...
1 comment
Read more