Bulk Importing of API’s to API Manager

In the last post we discussed on a tool that allows an admin to bulk export API’s from WSO2 API Manager. This is a useful tool if you have large number of API’s that needs to be exported. This blog looks at another tool that I have written to import API’s to an API Manager. Bulk importing of API’s may not be as common occurrence as bulk export, in many cases API’s are selectively imported to the API Manager rather than importing everything at once. However you can still identify which API’s to be imported and include them inside a folder where the tool will pick all the API’s inside the folder and import them to the WSO2 API Manager. The source code and instructions on how to run this tool can be found in the following Git Repo.




Publish custom data from API Manager to WSO2 Business Activity Monitor

WSO2 API Manager provides out of the box integration with WSO2 Business Activity Monitor (WSO2 BAM), this integration would allow API Manager to publish a pre-defined event stream which would be stored, processed and summarized by WSO2 BAM to provide a meaningful set of information in the API Manager dashboard. A case may arise when an organization wants to publish custom data to the WSO2 BAM. For example a user may want to publish some values which are passed in the response message header to WSO2 BAM. In such a case the existing data Publisher needs to be customized to accommodate this custom value. API Manager’s extension mechanism allows you to write your own class to do this. In order to do this you can extend the ‘APIMgtUsageDataPublisher’ class and write your own data publisher. Given below is a custom data publisher written to pass a custom value to the WSO2 BAM. Please note that this is similar to the existing data publisher class with the difference of it using a custom DTO to publish response data.

This custom data publisher refers to a ‘CustomDataBridgeResponsePublisherDTO’ to publish data to WSO2 BAM. Given below is the custom DataBridgeResponsePublisherDTO.

As you could see here, we have add a ‘customValue’ field to the original datastream , and when creating the payload the custom value is included in the payload. In this example we are passing a string as the custom value, this logic can be replaced to pass any other value to WSO2 BAM.


Once you have done this changes build the source and add the jar file to the following folder.



Java project file is attached for you to customize the values as required and build (through Maven).

Once this is done lets add the datapublisher class to APIManager.xml file. Lets modify the file to reflect the details of our custom data publisher. Given below is a sample snippet of the file. Notice that the custom data publisher is included as the ‘PublisherClass’ and the version of the response stream has been changed to’1.1.0′.

Now lets look at the changes needed to be done to WSO2 BAM, we need configure WSO2 BAM to expect this new data stream. You can do this by configuring the API Manage toolbox to include this value. The toolbox can be found in the following location.


The toolbox is a compressed file (.tbox format) that can be uncompressed, amended and re-compressed backed to a ‘.tbox’ file. I have attached a modified ‘.tbox’ file with this blog. This toolbox is configured to accept the field ‘customValue’ received in the response data stream.

Once you have a modified toolbox you enable statistics from the ‘admin-dashboard’ of API Manager which will automatically install this new toolbox to WSO2 BAM. Please make sure that you have uninstalled any existing API Manager toolbox before doing this.


You have now configured to publish a custom data value from WSO2 API Manager to WSO2 BAM


Git Project for the this example is given below. Toolbox is also available within this project.


Role based API Throttling through WSO2 API Manager

If you are already familiar with the WSO2 API Manager you would know that the API Manager provides the capability to apply throttling tiers to an exposed API. A throttling tier is an access limit which is applied to a given API subscription to make sure that API’s are not used over and above the expected level. WSO2 API Manager’s subscription plan is such that an API Subscriber can choose from a set of throttling tiers available to him when subscribing for an API. By default all the throttling tiers are available for all users. 

In real world an organization would want to have control over how users can subscribe and access their API’s. Opening up all the tiers to all users may not be acceptable. In order to address this concern API Manager provides a capability to assign roles to different throttling tiers hence only users belonging to a given role would have access to that particular throttling tier. Lets take the following example. You would have multiple user groups such as internal developers, registered external partners, and guest external partners. You would want to open up your API’s for these users but want to have different plans to these users. For this example we will only be dealing with the existing throttling tiers, based on this I will create the following mapping of user roles to tiers.

Bronze Tier - No Restriction
Silver Tier - All users expect guest external partners
Gold Tier   - Only Internal developers and Admin users
Unlimited   - Only Admin users

These restrictions can be created from the API Publisher’s user interface. In order to do this, login into the Publisher console as a API Publisher. Once you are logged in you will see the ‘Tier Permissions’ link on the left hand navigation panel. Click on the this link. Once you are in the Tier Permission page set the roles to which you need to ‘Allow’ or ‘Deny’ to a given throttling tier.tierPermission

You can Create your own throttling tiers [1] and then define how these tiers should be made available to different application developers using the Tier Permission option provided available in the API Publisher.

[1] https://docs.wso2.com/display/AM191/Adding+new+Throttling+Tiers

Accessing an OAuth 2.0 secured API in WSO2 API Manager with a SAML 2 Bearer token

One of the key feature provided by the WSO2 API Manager is its ability to secure the exposed API’s using OAuth 2.0 tokens. WSO2 API Manager supports all 4 grant types of OAuth 2.0 specification. OAuth 2.0 is a specification that is widely adapted especially in the mobile application space. However we still find the need for API’s to be accessed by web applications that still use standard username-password based credentials. Many of these web applications use SAML 2 based authentication and would prefer to use the same SAML assertion to access OAuth 2.0 protected API’s. This type of a scenario is supported by WSO2 API Manager which supports a SAML 2 Bearer grant type that can allow an application to exchange the SAML 2 bearer token with an OAuth 2.0 access token. This token exchange is transparent to the end-user hence it will not impact their user experience. This token exchange process can be depicted in the diagram below.diag

Step 1 – Application receives a SAML assertion from the SAML IdP after authenticating the user.

Step 2 – When the Application needs to invoke an API, it sends the SAML assertion to the token endpoint of the API Manager. SAML assertion is Base 64 encoded and sent as a SAML Bearer grant. Application will also need to send the consumer key and consumer secret which has to be obtained when subscribing to this API.

Step 3– API Manager will validate the request and exchange the SAML token with an OAuth 2.0 access token and a refresh token.

Step 4 – Application Access the API with the OAuth 2.0 access token (generated in the above step). This OAuth 2.0 token should be included as the Authorization header when invoking API’s via the API Manager.

The objective of this blog is to introduce the concept of token exchange, you would find detailed instructions on how to set this up in the following API Manager document.