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

WSO2 Cloud

Introduction WSO2 Cloud consists of three commercial cloud offerings namely the API cloud, Integration Cloud and the Identity Cloud. WSO2 Integration Cloud WSO2 Integration Cloud is a public hosted version of the powerful, 100% open-source WSO2 Enterprise Integrator. It allows you to host your cloud-to-cloud, cloud-to-on-premise integrations and API backends on a scalable cloud platform WSO2 API Cloud WSO2 API Cloud is an enterprise-ready, self-service platform that enables you to expose business capabilities as managed APIs and leverage off-the-shelf potential for advertising and selling business APIs. The API Cloud supports all aspects of an API’s lifecycle, from its creation to publication and retirement. The API Cloud is based on WSO2 API Manager , WSO2’s complete solution for designing and publishing APIs and managing a developer community. [2] WSO2 Identity Cloud WSO2 Identity Cloud leverages the functionality of WSO2 Identity Server’s identity and ac...
1 comment
Read more

Adding error sequence to a custom sequence

In my previous posi i explained how to call an endpoint using the call mediator. Usually when errors are thrown from the call mediator we can handle them using a custom sequence. When call mediators fails the execution stops hence handling errors is very essential. For this post I will be modifying the same sequence which i created in the blog post [1] The change which we need to do is we need to modify the sequence definition to map with the error sequence as shown below. You can find the modified sequence here . <sequence xmlns="http://ws.apache.org/ns/synapse" name="countrySequenceWithError" onError="countryErrorSequence"> <property name="uri.var.countryCode" expression="$url:countryCode"/> <property name="REST_URL_POSTFIX" scope="axis2" action="remove"/>     <call blocking="true">         <endpoint>             <http method="get" uri-temp...
2 comments
Read more

Exposing a SOAP service as a REST API

In this post i will be explaining how we can transform a SOAP based backend to receive requests in a restful manner through the WSO2 API Cloud. Steps. First log into the WSO2 Cloud and navigate to the API Cloud. In the API cloud select the option to add a new API. We will be creating an API to demonstrate an invocation to the backend soap service ws.cdyne.com/phoneverify/phoneverify.asmx?wsdl Give a name, context and version to the API and add a resource name with a GET Method. The resource name can be anything which you like since we will invoke the actual service usiing a custom sequence. Mention the URI template as indicated in the below screenshot. Next go to the implement tab. And select the endpoint type as HTTP/SOAP Endpoint and specify the endpoint as http://ws.cdyne.com/phoneverify/phoneverify.asmx. There is an important step we need to do here. We need to set the SOAP version for this request. In order to do that we need to select the advanced option ...
2 comments
Read more