WSO2 API Manager Beta is Out

WSO2 API Manager 1.0.0-Beta1 is now up for grabs. You can download the binary distribution from here. This release comes with many bug fixes, functional enhancements and UI improvements. A full list of issues resolved for this beta release is available here.

One of the most significant changes done in this release is changing the URL contexts of the default API Publisher and API Store portals. API Publisher which was previously accessible on https://host:port/apiprovider has been moved to https://host:port/publisher. API Store which was previously available on http://host:port/apistore is now available on http://host:port/store.

We intend to release another beta version (1.0.0-Beta2) of API Manager before we make the final 1.0.0 release candidate available. In the meantime please try out our latest release and give us your valuable feedback on dev@wso2.org or architecture@wso2.org.

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.

WSO2 ESB Tips & Tricks 09: Introduction to REST APIs

REST API support is one of the coolest features we have added to WSO2 ESB in the recent past. It was first released in last December along with WSO2 ESB 4.0.3, and we have already seen a fairly large number of users embracing the new feature. I blogged about this addition in last January, in an introductory post about the WSO2 ESB 4.0.3 release.

Today I intend to briefly describe how we can start using this feature in simple integration scenarios. Assume you have an account management service implemented on a SOAP stack such as Apache Axis2. Your service may support basic crud operations such as create-account, read-account, update-account and delete-account. The create-account operation would take several inputs and create the account in a backend business system. Usually each account would be associated with some sort of a unique ID which can be passed in as a parameter to read, update and delete operations. Now assume that you want to expose this SOAP service through a RESTful API. Many architects and developers are currently looking for ways to easily expose existing SOAP services over REST, so that the services can be easily consumed by mobile clients and other web clients. With the REST API support in WSO2 ESB, such a REST to SOAP conversion is like an evening stroll in the park. Here’s the API configuration for the create-account operation.

<api name="AccountManager" context="/accounts">
 <resource methods="PUT">
    <inSequence>
       <payloadFactory>
          <!-- Create custom SOAP payload -->
       </payloadFactory>
       <send>
          <endpoint>
              <address uri="http://backend.service/url" format="soap11"/>
          </endpoint>
       </send>
    </inSequence>
    <outSequence>
       <property name="HTTP_SC" value="201" scope="axis2"/>
       <send/>
    </outSequence>
 </resource>
</api>

The above API can be invoked by sending a HTTP PUT request to the URL http://host:port/accounts. The payload of the request should have all the parameters required to create the account encoded as a XML document, a JSON string or any other suitable format. The ESB would do the REST to SOAP conversion and invoke the backend SOAP service. The response from the backend service will be sent back as a RESTful response with the HTTP status code 201. If possible it is also possible to add a custom Location header to the outgoing response. In a proper RESTful design, the Location header should be URL which points back to the read-account operation of the REST API.

Similarly more resource elements can be added to the above API to expose read, update and delete operations of the backend service. The full configuration would look something like this.

<api name="AccountManager" context="/accounts">
 <resource methods="PUT">
    ...
 </resource>
 <resource methods="GET" uri-template="/account/{accountId}">
    ...
 </resource>
 <resource methods="POST" uri-template="/account/{accountId}">
    ...
 </resource>
 <resource methods="DELETE" uri-template="/account/{accountId}">
    ...
 </resource>
</api>

Note how we map each HTTP verb to a unique operation in the backend service. Also note the usage of URI templates to specify request URL patterns to accept. WSO2 ESB has full support for level 1 and level 2 URI templates as described in the URI templates draft specification. Alternatively you can also use servlet style URL mappings to configure your API resources.

<api name="AccountManager" context="/accounts">
 <resource methods="GET" url-mapping="/account/*">
    ...
 </resource>
</api>

I believe the above example gives a basic idea on how the REST API support in WSO2 ESB can be used to implement real-life integration solutions. While this feature can have many potential use cases, one of its most powerful capabilities is to expose existing SOAP services and legacy systems over REST. Thanks to the REST API support in WSO2 ESB, implementing a RESTful overlay for an existing application is easier than never before.

Latest WSO2 ESB Performance Numbers

WSO2 ESB is one of the fastest enterprise service bus solutions around. It's lightweight, doesn't eat up too much memory and CPU, and capable of handling thousands of concurrent requests with only a handful of worker threads. An out of the box WSO2 ESB installation configured for a pass through scenario, can provide a throughput close to 6000 transactions per second on average.

And it gets better. WSO2 ESB comes with a couple of performance optimizers that can be used to get an even higher throughput from the ESB. Recently we did a performance benchmark between these different performance optimizers and the mint WSO2 ESB. We have now published the results of these tests at our website. According to the results, the pass through HTTP transport, our latest performance optimizer, provides the highest throughput. With 2000 concurrent connections sending 1K sized messages, the pass through transport could provide a throughput of 18000 transactions per second.

One of the limitations in these performance optimizers is that they restrict the type of scenarios that you can run on the ESB. For instance the pass through transport currently can only support pass through proxy scenarios. It cannot be used with transformation or any other type of payload manipulation use cases. We are currently working on making the pass through transport capable of dealing with such content aware scenarios as well. In fact we want the ESB to run with the pass through transport by default for all scenarios.

Introducing JAVA Colombo: The Sri Lankan Java User Group

Sri Lanka is home to a large number of Java developers. Hundreds of Sri Lankan programmers are involved in writing Java code for various open source and proprietary projects. Unfortunately though, we haven’t had the notion of a strong Java developer community in Sri Lanka up until now. However starting from next week that’s about to change. We are starting JAVA Colombo, a Java User Group (JUG) for all Java developers in Sri Lanka. JAVA Colombo will serve as a regular meeting place as well as a knowledge sharing hub for any Java programmer interested in taking part. We intend to have regular meetups and other educational events in and around Colombo to help developers learn and connect.

Our first official meetup will be held on 15th of March 2012 at 6pm at WSO2 premises. This will be a great opportunity for Sri Lankan Java developers to meet each other and have a taste of the JUG experience. To make the meetup even more interesting we are also planning to have an expert panel discussion on the topic “Secure Coding with Java”.

If you are a Java programmer or a Java enthusiast and you wish to become a part of this effort, please sign up today at meetup.com.

High Volume Web API management with WSO2 ESB

During last year's WSO2Con, Paul Fremantle and I co-presented on the topic "High Volume Web API management with WSO2 ESB". There we discussed how WSO2 ESB is specifically designed to handle large volumes of traffic received over many concurrent connections. We explained the multithreading, streaming and non-blocking IO aspects of the ESB while looking at some of the high performance extensions we offer such as the message relay and the pass through HTTP transport. We also went through some ESB and JVM performance tuning basics taking the WSO2 ESB deployment at eBay as a case study.