Saturday, January 26, 2013

WSO2 APIManager integration with WSO2 BAM


From this blog-post,I'm going to dig into the implementation of monitoring support provide by WSO2 API Manager with WSO2 BAM integration.First you need to know how to configure WSO2 AM with BAM to start with.You can find about the related configuration details from our product documentation
However,before continue with this post,I think its better if I explain one step of above configuration.It's the AM Stats toolbox[API_Manager_Analytics.tbox] deployment in BAM server.This toolbox can be found from {AM_Home}/Statistics folder.A toolbox can be defined as an installable archive in BAM[1].This AM Stats toolbox contains below artifacts.
  • Stream Definitions -These are the descriptions of streams of data to be sent to WSO2 BAM in order to perform analytics.
  • Analytics-Analytics include the hive scripts to be deployed in WSO2 BAM.
Below diagram shows the main flow of the integration between WSO2 API Manager and WSO2 BAM.I will go through each step by step.


[1] Once a user trying to invoke a published API,the request will go through the engaged API handlers for that specific API as explained in here.

[2] The request will hit APIUsageHandler implementation class and once you configured AM server with enabling BAM monitoring support.

[3] From this handler implementation,it'll direct to Usage Publisher implementation in order to create an event from the request and  push that event to BAM side.Note that from AM side,three types of events will be  push in to BAM server as listed below.
  • An event with successful API invocation request
  • An event with fault API invocation request
  • An event with API response
[4] Once such event received from BAM side,first it check the sent event matched with defined stream definition in AM stats toolbox deployed in BAM server.There are three pre-defined stream definitions can be found from AM Stats toolbox as mentioned below.
  • requestStreamDefn
  • faultStreamDefn
  • responseStreamDefn
If the event matches,that event will stored in local Cassandra data store and else an error will thrown.

[5] Then with BAM inbuilt analyzer engine support,by using the relevant analyzer script [hive script],which can be found from AM Stats toolbox,the data in local Cassandra space will be analyzed and populate to relational database tables.

[6] Next with Usage Client implementation of WSO2 APIManager,that created BAM side relational database will be directly accessed and retrieve data from the db tables,by querying them.

[7] Then from API Publisher UI,those queried data will be pulled out and shown them in pre-defined graphs.

[8] Once an API Creator logged into publisher UI,he can view the statitics related to his created API.

[9] Additionally since the graphs defined in publisher UI is limited,a user can directly use the BAM node to show stats from gadgets in BAM dashboard as explained in here or either generate pre-defined/custom reports from the stored data as explained here.

References

[1] http://docs.wso2.org/wiki/display/BAM200/Introduction+to+BAM+Toolbox

Friday, January 25, 2013

Dig in to generated API Template from WSO2 API Manager

As the starting blog-post for 2013,I thought of summarizing about the implementation of key features of WSO2 API Manager as security,throttling,monitoring aspects by explaining a bit of API template.In WSO2 API Manager,once a API creator create the API from publisher app UI and change its status as 'PUBLISHED' ,a template xml for that API will be generated with its input attributes of name,version,context,endpoint,etc.

You can find that generated template from '{AM_Home}/repository/deployment/server/synapse-configs/default/api'.Below is such a generated sample API template.

When you observe that API,you'll notice for each API resource there's a separate in sequence and an out sequence created.And additionally apart from the input data added by the creator,you'll notice for an API ,four handlers have been engaged to each published API.



Each of the above handlers contain the implementation of key providing features of WSO2 API Manager.You can find each of the implementations of these handlers from  here.
An API Handler provides QoS features like security,throttling,monitoring for an API.
If I explained a bit of each of these;

  1. APIAuthenticationHandler -This provides the API Authentication support with OAuth2.0.All the API resource level authentication schemes handling through this handler.
  2. APIMgtUsageHandler- This provides API monitoring support with WSO2 BAM integration.
  3. APIMgtGoogleAnalyticsTrackingHandler-This provides API monitoring support with Google Analytics support.
  4. APIThrottleHandler-This provides API throttling handling support with pre-defined throttling policies.
  5. APIManagerExtentionHandler-This is a extention handler,looking for a in/out sequence with a pre-defined name pattern to be invoked if exits such named sequence.This handler first looks for a sequence named WSO2AM--Ext--[Dir], where [Dir] could be either In or Out, depending on the direction of the message. If such a sequence is found, it is invoked.Additionally below more API specific extension sequence is  also looked up by using the name pattern apiName--[Dir]. If such an API specific sequence is found, that is also invoked. The above searching sequences can be in global level or at the per API level.
Same-way,if you want to add a custom feature to support from API level,you can achieve it by writing a custom handler and engage it to the generated API template.To write such a custom handler ,you can find more information from here.
When an API invocation request comes to API Manager,first the request will process through the engaged handlers of the API element in sequential order.And if the request pass through each security,monitoring, throttling handling layers,it will direct to the relevant API resource.