Managed APIs with WSO2 API Manager

In this post we'll take a look at what Managed API's are and how to expose your API's as managed API's using the WSO2 API Manager.

APIs

An API is a business capability delivered over the Internet to internal or external consumers. API's provide a means for vendors to provide their software as a service (SaaS) remotely to other parties. API's hide the underlying implementations and provide consumers with a standard programming interface to access functions.

For example there are many calendar apps that can access your google calendar and display events that are on it. This is made possible by the Google Calendar API. Many websites have YouTube videos embedded in them, this is done by using YouTube APIs.

Most service providers expose their services as API's. Yahoo, Amazone, Facebook, TripAdvisor and eBay to name a few.

eBay gives a good crisp intro as to what their APIs allow you to do: https://go.developer.ebay.com/developers/ebay/products/what-ebay-api

Managed API's

So what are managed API's ?

Say you operate a service that provide customers with reccomendations to purchase/sell stocks based on current market trends and predictions. You want to monetize this service and charge for API usage.

You want to expose your API's to both stock brokers and individual clients who wish to do trading on their own. You intend on having different account registrations for individual clients e.g: Basic accounts will have a lesser monthly subscription fee but with a limited number of API calls allowed, Silver/Gold subscriptions will have a higher number of permitted calls while Premium accounts will allow unlimited API calls. Furthermore, stock brokers will be charged differently based on the number of calls they make.

This type of service requires Managed API's. You should be able to authenticate and authorize users, limit access (throttle) and collect statistics in order to monetize the API's.

With Managed API's you can do the following:

Actively advertise API's and allow subscriptions to them
Can Secure API's and carry out authentication and authorization
Monitore and monetize with analytics
Throttle access
Enforce Service Level Agreements (SLA's)

The WSO2 API Manager is a product that allows organizations to expose their business functionality as Managed API's.




The API-M is made up of 4 components, namely the API Publisher, API Store, API Gateway and Key Manager.

API Publisher: allows developers to publish API's, manage API versions, govern the API life-cycles, apply security policies, attach related documentation etc.

API Store: is a store where API's are advertised. Subscribers can discover and subscribe to API's using the API Store. There is a public user store as well as tenant based user stores.

API Gateway: the API Gateway is where API's are deployed. It intercepts API calls and enforces SLA's, performs security checks (using key manager), handles throttling and passes it to the actual back end service. The gateway also publishes API data for analysis.

Key Manager: handles security key related operations and token validations.

In this example we'll use an existing weather API in order to demonstrate how to create a Managed API using it.

OpenWeatherMap provides free weather data based on City. The following service call returns a JSON request which gives you the current weather in London:
http://api.openweathermap.org/data/2.5/weather?q=London

We'll create a managed API using this service as the back end.

Download and extract WSO2 API-M from here.

Start the server by going to <PRODUCT_HOME>/bin and by running wso2server.bat (Windows) or wso2server.bat (Unix).

Once the server starts you will see 3 url's displayed. By default they are:

http://your_ip:9443/carbon - Admin console url
http://your_ip:9763/publisher - Publisher url
http://your_ip:9763/store - Store url

These ports can be changed by incrementing the <offset> value in <PRODUCT_HOME>/repository/conf/carbon.xml

WSO2 products adhere to a role based permission model. Users are granted permissions based on the roles assigned to them. Permissions are assigned to roles, not the users.

Create 3 roles that allow creating API's, publishing and subscribing. Log in to the Admin Console using the default username/password : admin/admin and follow the instructions in the following documentation to create user roles: User Roles in the API Manager

Now add 2 users 'provider1' with create and publish roles assigned and 'subscriber1' with subscriber role assigned. Follow the steps listed in: Adding Users

Now log into the Publisher (http://your_ip:9763/publisher) using the 'provider1' user

The above screenshot shows some already existing API's. If there are no API's created yet this page will be blank.

Create API

Now Click on Add in the left panel.

Fill in the details as shown below:

Context will be the URI context path of the API
You can have many versions of the same API; define a version number
you can add a Thumbnail to your API as well

You can add Resources by defining a URL pattern and selecting the HTTP verbs that are associated with it. If you don't do this you will be prompted to add a wildcard resource (/*) with all 5 methods associated with it.

Click on Save.
Then click Implement

give the production endpoint as: http://api.openweathermap.org/data/2.5/weather

you can enter a Sanbox endpoint as well if needed for testing.

Now click Manage

Tier Availability means what throttling tiers would be available for subscription.

by default the API-M ships with 4 throttling tiers: bronze, silver, gold and unlimited. You can add more tiers based on your requirement.

Access to API could be throttled in a fine grained manner at Resource/verb level:

Click Save & Publish and the API will be Published. Optionally you can just save the API and publish later. If the user you are logged in with does not have Publish permission you will not be able to publish.

Notice the Copy button below. That allows you to easily copy the API and create a new version.

You can manage the Lifecycle by going to the Lifecycle tab.

API Store

Now lets take a look at the API Store - http://your_ip:9763/store

You will be taken to the public store. API's will be listed in thumbnail views similar to a mobile app store.

Log in using the subscriber credentials we created: subscriber1/subscriber1

Now you can Subscribe to an API. Click on the Weather API to subscribe to it.

You will see 2 drop-downs. One to select the Application and the other for the Tier.

Application - Applications allow API's to be grouped together. A single application may have one or many API's. Access keys are issued on an application basis, not on an API basis.

By default the application selected would be 'DefaultApplication'. Click on the dropdown and select New Application.

This will direct you to create a new application.

Notice the application allows you to define a Throttling Tier as well. This will throttle out all API access at Application level once the quota is exceeded even if individual API's have not reached their throttle limit. Lets select Gold for the application.

Once the application is added select Silver for the throttling tier of the API and click Subscribe.

API Manager uses OAuth 2.0 for authentication. Go to My Subscriptions and select the weatherApp. Click on Generate under Production and Sandbox (if needed). This will generate aConsumer Key, Consumer secret and also an Access Token that could be used for testing.

A token validity period could be set for the Access token and you can Re-generate it when ever required.


Testing the API

The API Store ships with a RestClient that helps you test your API's Restfully.

Under tools select RestClient.

Use one of the production URL's from the WeatherService API page (click on WeatherService API to go to the page).

Copy the Access token which was generated in our previous step.

Add url with the query parameter: q=London
Pass the token by specifying it as: Authorization :Bearer 36bd42e345c1bb027ce952255918f4
Note: B in Bearer should be Capital


Now you'll get the weather in London as a JSON response;

Throttling:

Remember we set the throttling tier to Silver for the Weather API. Now send more than 5 requests within a minute using the rest client and see what happens.

You will get a Message Throttled Out response with a code.

* Notice the response is in JSON. If you want to convert this to XML you can do so by editing the synapse configuration and setting the 'messageType' property in the outgoing message to XML. However, the more recommended way of doing this is by adhering to the API Façade pattern. Refer to my previous blog post: Format Conversion using API Façade Pattern