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.
WSO2 API Manager is really powerful Opensource API Management tool that would allow you to expose, secure, manage and monitor API’s exposed via the API Manager. The product now comes with a nice feature to export/import API’s from and to the API Manager deployment. This feature comes in handy when you want to migrate API’s from one environment to another or when you want to copy an API from one API Manager to another. The feature is exposed as a RESTful API that can be invoked from a REST client, CuRL or a 3rd party script.
The limitation of the current implementation is that it only allows a single API to be exported at once. This is fine for majority of use-cases but there may be some instances where you may have 100’s of API’s and it might not be practical to export each and every API individually. To avoid this situation I have written the following tool that would allow you to do a Bulk export of API’s from the API Manager. The code and the instructions on how to use this tool can be found in the following GIT repo.
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.
You can Create your own throttling tiers  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.
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.
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.
When exposing API’s for consumption it is of paramount importance that the API access is controlled so that service consumers are not able to misuse these exposed API’s. WSO2 API Manager provides the capability to throttle API’s that are exposed via the API Manager. API Manager allows throttling at multiple levels.
1. Application Level throttling
2. API Level throttling
3. Resource level throttling
To understand the above levels of throttling we need to first understand the concept of API’s and applications in the API Manager.
An application inside the WSO2 API Manager is a logical group to which API’s are subscribed into. For example if you take a Weather Application, this will have 2 API calls. First one would make a call to a Location API to get GPS coordinates of the current location, after which a second API call would be made to a Weather API to get weather information of the current coordinates.So in this case the Application within the API Manager would be the ‘Weather Application’ and both the Location API and the Weather API would be subscribed under this application. This can be illustrated in the diagram below
Lets related the above diagram to different throttling tiers that are available with the API Manager, this can be illustrated as below.
1. Application Level Throttling
Each application can have a throttling policy defined that would limit the aggregated number of API calls that can be made to API’s subscribed under that application. In this case we can throttle the number of API calls made from the weather application irrespective of whether they are calling the Location or the Weather API. A throttling tier can be associated to an application from API Store. This can be done by navigating to ‘My application’ tab as shown below.
2. API Level Throttling
Each API can be associated with a throttling tier. When an API is subscribed the subscriber would have a choice to choose which throttling plan to subscribe. This is shown in the screenshot below
The choice of throttling plans that needs to be associated to an API can be selected at the point of API creation. Given below is a screenshot which shows how to add a throttling plan to an API.
3. Resource Level Throttling
WSO2 API Manager also allows you to define throttling tiers for each resource within an API. This allows you to have more control on how each resource is throttled in a given API. In the above example the Weather API would have two resources ‘getWeather’ and ‘getFullWeather’ which can have two different throttling tiers. A throttling tier can be associated to a resource at the point of API creation. This is shown in the screenshot below.
If you wondering on how to set these tiers that you see on the screen, you can refer to the following API Manager documentation 
API Manager is shipped with the capability that allows the product to be started in a specific profile(for example a Gateway profile or a Key Manager profile). When the API Manager is started in a specific profile only the features specific to that profile and the common features as started with the server. For example if you start the API Manager with the Key Manager profile, only the features required for the key manager server and the set of features common to all profiles are started.
The feature bundling capability is provided using the underline OSGi architecture of the WSO2 API Manager. The API Manager is currently shipped with some server profiles which are documented in the following URL. This blog looks at how we can create our own profile within the API Manager.
Features relating to a given API Manager profile can be found in the following location
Bundles.info file contains the features that needs to be started with the given profile.
Lets create a new profile called ‘api-km-pub’. This profile will allow the API Manager to work as a Key Manager and a Publisher. For this profile I will merge the two bundle.info files in ‘api-key-manager’ and ‘api-km-pub’. The merged bundle file should be placed in the following directory structure below
You can now start the API Manager server with the newly created profile by executing the following command
WSO2 API Manager provides an intuitive UI that can be used to add and configure API’s that are exposed via the API Manager. However not all the capabilities of an API can be manipulated from the API Publisher’s UI. Certain tweaks require the access to the API definitions directly. There are two possible ways of doing this.
1. Via the Management console of the API Manager
Access the Management console of the API Manager from the following URL and log-in using the admin credentials.
Once inside the management console, you can see the source view icon on the left hand side navigation bar as indicated below. Navigate to the source view page.
Here you would find all the API definitions, you can change the API definitions as required.
2. Directly accessing the API definition from the file system of the API Gateway.
API definition is stored in the file-system of the API Gateway, you can access this from the following folder path.
Each API is represented by a xml file. You can change the definition by changing the contents of the file. The changes would be hot deployed to the API Gateway.
Please be mindful of the changes you make as it affect the exposed API’s. API’s are defined in Apache Synapse hence you would need some level of knowledge on Apache Synapse to manipulate these files.
WSO2 API Manager has the capability of restricting which grant types are enabled to a given application. This functionality is provided via the management console of the API Manager. Given below are the steps required
1. App developers should have the required permission in order to restrict the grant types available for an application. Permission given below should be set to a user role associate to the App developer.
2. Once this is done please log out and log into the API Manager’s admin console
3. Now you would see the OAuth URL available in the left navigation, click on this.
4. Here you would see all the applications that are created by the App developer, from this menu select the relevant application to which the grant types should be restricted.
5. Once you are inside the selected application you can define which grant types should be allowed to a given application. By default all grant types are ‘un-checked’ and all grant types are allowed. If you want to override this default configuration select on the required grant types that should be allowed to a given application.
6. Once you are done click on the update button and the configuration would be updated.
WSO2 API Manager provides a host of REST API’s that are capable of performing many operations in the API Manager. Given below are the steps to follow to retrieve token information such as the Consumer Key,Consumer Secret, and Access Token using the REST API. In order to perform this we assume that an instance of the API Manager is running(in port offset 0) and an application is already available in the API Store.
1. Initially you need to login to the API Store and create a cookie that can be used in subsequent REST calls. Login to the store using the following command. Replace the username and the password with the relavent value
curl -X POST -c cookies http://localhost:9763/store/site/blocks/user/login/ajax/login.jag -d "action=login&username=xxxx&password=xxxx"
2. Call the Generate Application Key API that would generate the required access keys. Use the below command to generate the application keys. The following command would generate keys for the default applications. Change the parameters accordingly based on your application.
curl -X POST -b cookies http://localhost:9763/store/site/blocks/subscription/subscription-add/ajax/subscription-add.jag -d "action=generateApplicationKey&application=DefaultApplication&keytype=PRODUCTION&provider=&tier=&version=&callbackUrl=&authorizedDomains="