Hello World with WSO2 API Manager

A couple of months back, I took a little break from WSO2 ESB related work and focused my attention on WSO2 API Manager, one of our new and upcoming products. WSO2 API Manager is an enterprise grade, open source API management solution which solves a number of technical and business challenges faced by API providers as well as API consumers. It provides a simple, yet feature-rich platform for API providers to create and manage APIs. WSO2 API Manager is designed with software development and distribution best practices in mind which makes API governance, SLA management and monitoring absolutely trivial. For API consumers it provides a sleek, user friendly, App Store like experience where the consumers can browse through published APIs, subscribe to them, obtain API keys and provide feedback on APIs. 

In this blog post, I intend to walk you through some of the basic features of WSO2 API Manager. It’s written in the form of a short tutorial so you can actually try this out on your own. I’m going to start at the absolute beginning (downloading and installing the product), so hopefully you will be able to follow the material without any hiccups. I will provide more in-depth architectural details regarding WSO2 API Manager in a future post. 

Setting Up

Last week we announced the 1.0.0-alpha release of WSO2 API Manager. You can now download this version from our website. Start by downloading the binary distribution (wso2am-1.0.0-alpha.zip).The only prerequisite needed to run WSO2 API Manager is an installation of JDK 1.6 or higher. We generally recommend Oracle (Sun) JDK 1.6.0_23 but it should work fine on later versions of the JDK too including JDK 1.7. So far we have tested this release on Windows, Mac OS and several flavors of Linux. So if you have anyone of these operating systems with a JDK conforming to the above specs, you should be in a position to install and run WSO2 API Manager.

To install, simply extract the downloaded archive. Then open up a shell (or a command prompt if you’re on Windows) and go to the bin directory of the installation. You will find several shell scripts and batch files in this directory. To start the server up, just execute the wso2server.sh script (or wso2server.bat if you’re on Windows). You will start seeing a bunch of log statements on the console. Server start up may take several seconds. Wait until the server has fully booted up. When the server start up process is complete you will see the following log entry on the console.

[2012-07-07 01:30:31,154]  INFO - StartupFinalizerServiceComponent Server           :  WSO2 API Manager-1.0.0-ALPHA

[2012-07-07 01:30:31,155]  INFO - StartupFinalizerServiceComponent WSO2 Carbon started in 20 sec

[2012-07-07 01:30:31,415]  INFO - CarbonUIServiceComponent Mgt Console URL  : https://10.114.95.181:9443/carbon/

Creating APIs

Now we are all set to put WSO2 API Manager into action. Launch your web browser and navigate to https://localhost:9443/apiprovider. You should see the API Provider login screen as shown below.

Specify username and password as “admin” to sign in. You will be directed to the API Provider home page. This page usually lists all the APIs created. Since we are logging in for the first time and haven’t created any APIs so far, you won’t see anything here except for a welcome message and a “New API” button.

Click on the “New API” button which will take you to the “Add API” form. It’s time to create our first API. As our first example we are going to create an API named FindTweets which is based on the on-line search functionality provided by Twitter (See http://search.twitter.com). Consumers of our FindTweets API will be able to search for Tweets by providing a keyword as the input. Our API will accept both GET and POST requests and the output will be an Atom feed.

Enter following values into the respective fields of the Add API form. Optionally you can also download a nice looking Twitter icon and upload it as the API image. Leave other fields as they are.

• Name: FindTweets
• Context: /twitter
• Version: 1.0.0
• Endpoint: http://search.twitter.com
• Tiers: Gold, Silver, Bronze (select all 3 – this field supports multiple values)
• Business owner: Bruce Wayne
• Business owner e-mail: dark.knight@wayne-enterprises.com
• Technical owner: Peter Parker
• Technical owner e-mail: spidey@dailybugle.com

Once you have entered all the above values correctly, click the “Create” button to save the API configuration. You will be taken back to the API Provider home page where the new FindTweets API will be listed.

Now click on the FindTweet API. The API overview tab should get opened for you where you will be able to see a summary of the information you entered when creating the API.

Publishing APIs

When you create a new API, it's initially in the “CREATED” state. When an API is in this state, the consumers cannot see it in the API Store.  You can verify this by pointing your web browser to http://localhost:9763/apistore.  In order for the API to appear in the API Store, we should promote the API to the “PUBLISHED” state. To do this, go back to the API Provider home page and click on the FindTweets API. Select the “Life Cycle” tab, where you will see a drop down with different states the API can be in. 

Select the “PUBLISHED” state in the drop down and click the “Update” button to apply the state change. The API Provider will immediately start showing the API state as “PUBLISHED”. Now if you go back to the API Store at http://localhost:9763/apistore and refresh the page, you should be able to see the FindTweets API listed on the home page itself, before even signing into the portal.

Subscribing to APIs

Up to this point we have created a new API and successfully published it into the API Store. Now it's time to subscribe to our FindTweets API and start consuming it. Login to the API Store using the default administrator credentials (user: admin, pass: admin).  Click on the FindTweets API to go to the API overview page. There you should be able to see the “Subscribe” option. 

In order to subscribe to an API, you should first have an application in place. An application is a logical collection of APIs. Idea is that an API consumer (typically a developer) develops applications using one or more APIs. So the consumer can create a logical application in WSO2 API Manager, and subscribe to all the relevant APIs using that application. Afterwards the consumer can obtain a key against his/her application using which any API in that application can be invoked.

When you login to API Store for the first time, you are given an application named “DefaultApplication”. Select this entry in the “Applications” drop down. The “Tiers” drop down will list all the tiers you specified when creating the API. If you followed the instructions in this post to the letter, you should see Gold, Silver and Bronze listed here. Select the “Gold” tier and click on the “Subscribe” button. A pop up will appear asking whether you want to proceed to the “My Subscriptions” page. 

Select this option and go to the “My Subscriptions” page. There you should be able to see the “DefaultApplication” entry along with its subscription to the FindTweets API. 

Click the “Generate Production Key” option and then click the “Show Key” option to obtain a key for your application. Congratulations! You are now all set to consume the FindTweets API.

Testing the API

You can use any REST client to invoke the FindTweets API. For command line geeks like me, I can recommend Curl. If you're looking for some kind of a GUI tool, I can recommend Jmeter or SOAP UI. I recently came across a neat little Chrome extension named “Advanced REST Client” which is also a pretty awesome way to interact with the WSO2 API Manager.

If you're using Curl, the following command should invoke the FindTweets API and get you a result.

curl -v -H “Authorization: Bearer xxxxx” http://localhost:8280/twitter/1.0.0/search.atom?q=wso2

Replace the 'xxxx' with the application key you obtained earlier. If you pass the right key, the API Manager will route the call to search.twitter.com and get you an Atom feed consisting of all the recent Tweets tagged with the keyword 'wso2'.

Here's how you can try the same using the Advanced REST Client for Chrome.

Note how we are passing the application key in the Authorization header of the message, prefixed by the string “Bearer”. This is because WSO2 API Manager enforces OAuth security on all the published APIs. Any consumer that talks to the API Manager should send their credential (application key) as per the OAuth bearer token profile. If you don't send an application key or send a wrong key, you will receive a 401 Unauthorized response in return.

Also remember that we subscribed to the FindTweets API using the “Gold” tier. This tier only allows 20 requests per minute. So if you keep sending requests fast, after 20 requests the throttling policy will kick in and you will start receiving 503 responses.

So there you have it; a simple 'Hello World' scenario with WSO2 API Manager. I'm sure at this point you're itching to try out more use cases with this product. Here are a few things you can try out:

1. Add more users with different permissions and see how the user experience changes according to the available permissions
2. BAM integration for monitoring APIs
3. Adding API documents
4. Rating and commenting on APIs
5. Deprecating and blocking APIs

Expect a few more blog posts from me covering the above topics. If you want to see a recording of the scenario I have described above, take a look at this webinar recording. Last but not least, go through this blog post by Kin Lane, the famous API evangelist.