Tuesday, December 18, 2012

Internationalization Support for APIManager apps

This requirement came from some of the users who are already using WSO2 API Manager product and from WSO2 AM 1.3.0 on wards [released on today],this feature has implemented.You can find WSO2 AM 1.3.0 binary pack from here.

Basically for the two apps [Publisher/Store] in WSO2 API Manager,now a developer can change app labels/messages according to the set language in the web browser.

From this blog-post,I'll explain the steps to localize publisher app to Spanish,which contains unicode charactors.

1. First set the browser language to your preferred language.
 Eg: In Google chrome navigate to Settings->Show advanced settings->;Languages and select your preferred language.

2. set the browser encoding type as UTF-8.

3. Then let's change the publisher app accordingly, Extract your downloaded pack and navigate to the deployed publisher app from the location "AM_Home}/repository/deployment/server/jaggeryapps/publisher".

4. We have kept two resource files to define Strings with key as one resource file [eg:locale_en.json] to store the Strings defined in .jag [jagggery] files according to browser locale,while another resource file called 'i18nResources.json' to store Strings defined in client side javascript files such as popping up message strings when an UI event triggerred. You can find the location for these two files from  the above publisher deployment folder with browsing through  'publisher/site/conf/locales'.



5. The jaggery related resource files are located at 'publisher/site/conf/locales/jaggery' folder while javascript resource file is located at   'publisher/site/conf/locales/js' folder.


6. Localize Strings defined in jaggery files

In this blogpost ,since we are going to localize the app with Spanish,first to localize Strings defined in jaggery files,you need to add a new file with your browser set locale value.Say your web browser langauge set to Spanish thus relevant locale code is 'es'. 
Then you have to create a new file called locale_{lolcaleCode}.json [Here that file has to name as locale_es.json] inside 'publisher/site/conf/locales/jaggery' folder  and add the key-value pairs.

Please refer the default resource file for jaggery,that we have added to same above location called 'locale_en.json' and how we have defined key-value pairs for Strings.Below is a part from locale_es.json file I created.


7. Localize Strings defined in client side javascript files

To localize the javascript UI messages,navigate to  'publisher/site/conf/locales/js  and update the json file called "i18nResources.json" with relevant values for the key strings.

That's all.Once you browse changed publisher app view with Spanish,it'll be as below.



Implementation Details


If you much familiar with jaggery apps,you may know that all the strings shown from the app,are defined in either server side jaggery files [.jag files] or in  client side javascript files [.js files]. 

To implement localization support for jaggery,we have used its inbuilt script module called 'i18n' and its functionalities.For more info refer http://jaggeryjs.org/apidocs/i18n.jag

To implement javascript localization support,we have used MIT licensed js plugin called 'i18next' support and it's inbuilt functions.For more info refer http://jamuhl.github.com/i18next/



Tuesday, November 27, 2012

Generate Application Tokens & User Tokens from WSO2 API Manager

WSO2 API Manager provides a complete solution for publishing APIs,creating and managing a developer community and a scalable routing API trafic.If you are already familiar with this product,you are familiar with its one of basic component -'API Store'.

A deployed API Store provides a single place to all third party and internal API consumers to browse available APIs and subscribe to them as they want.If such a consumer follow the subscription process of this store-front UI,he'll notice it's a process of subscribing a selected set of APIs into a application and  giving a result with generated three keys as access token,consumer key and consumer secret adhreing to OAuth 2.0 spec.
In other words,it's the process of an Application developer [Say John a mobile app developer] select the APIs which needed to use from his application and subscribe to those APIs from his created application.As the result of this subscription process the application developer,John is getting an application access token,that can be used to invoke the subscribed APIs while developing the application and other two values called Consumer Key and Consumer Secret which are useful when the application users [third-party users who will use John's mobile application ] trying with his developed mobile app.




Now I know,you will have an important question with the above information given by me.It's that though Store-front is helpful to app developers  to find,select and subscribe to suitable and available APIs for developing applications,how the developers can handle authentication of application users to his developed app with the aid of WSO2 API Manager solution.The answer is from WSO2 API Manager we are exposing a separate endpoint,to achieve this requirement called 'Login API'. 



This has deployed as a separate pre-defined API from API Manager and from this API,it's calling an OAuth endpoint to generate access tokens.The source view of 'Login API' is as below.You can browse it from API Manager,by browsing carbon console ->Manage->Service Bus->APIs .



The developed app has to implement in a way,first the app has to store the consumer key and secret generated for the app from store front.Then once a app-user trying login to it,a request will send to above exposing login API endpoint with username/password and consumer key/secret values.Then from the login API,it'll send back a user access token ,a refresh token and an expirary time for the tokens for each success request. By using the returned user access token after a key validation,app user can use it to authenticate to functions of the app.

Below steps will explain how to send a Curl request to above 'Login API'.App developer can implement sending this request and getting the response as a part of his app implementation.
  1. First get the relevant generated Consumer Key and Secret for the app from API Store and combine those two values as "consumerKey:consumerSecret".
  2. Then encode that combined value as base64 encoded value,For that you can use online encoder bae64encode.org .
  3. Then set that encoded value as the Authorization header for the request.The authorization header type for this request is 'Basic'.
  4. And pass username/password values as query strings.
  5. The complete sample Curl request is as below.
curl -k -d "grant_type=password&username=xxxx&password=xxxxx&scope=PRODUCTION" -H "Content-Type:application/x-www-form-urlencoded" -H "Authorization:Basic Base64EncodedValue(ConsumerKey:ConsumerSecret)" https://localhost:8243/login

Above Curl request will return with a user access token,refresh token and an expiration time for tokens.

Saturday, November 3, 2012

Running a SQL script at build time of a maven project

The above requirement was arisen while working on an implementation of a WSO2 carbon platform feature.I'm planning to write another blog post on how I acomplish writing that feature in a seperated blog.Until that from this blog,I'll explain,how I achieve one part of that work-Run a database sql script on a specific database while building a maven project.This was achieved through using the Apache Maven AntRun Plugin.

This plugin could embed to a maven module pom and simply execute it while building the maven project from its pom.What you have to do is add the sql task as the running goal inside the above plugin as shown in below and the full pom.xml can be found from here .If you are going to add this plugin to a pom.xml of a maven project,add it to section of the pom.Note how the jdbc driver,database url,database username/passwords and the database script defined in the plugin.

Sunday, October 28, 2012

Extending WSO2 API Manager



WSO2 API Manager consists with two web applications as APIStore and APIPublisher. APIPublisher UI is important to create/publish APIs and APIStore UI is useful to create applications/subscribe to published APIs.

If we think about a use-case of  a company in which adopted the WSO2 APIManager solution; above Store/Publisher apps need to interact with third party users,not only with company internal employees.Such that in real business case,it's really important and useful if below two facts can be achieved through WSO2 API Manager apps.And ofcourse,it has proven that the below facts can be achieved from WSO2 API Manager.
  • Customizing both Store/Publisher apps
Customization is really needed,if the company want to host the two apps with using a customized theme and their logos.This can be easily done by the steps described in here.
  • Host Store/Publisher apps in a public domain own by the company
Host the apps in a public domain is a real world business requirement as above Store/Publisher apps need to interact with third party users.You can achieve this by following below steps.

NOTE: You have to try with API Manager pack from 1.1.0 on wards.Download the pack from here and extract it.


1) Open carbon.xml from the location {APIManager_Home}/repository/conf/ and uncomment below entries   
   , and add the related hostname value to them,

 To set the custom hostname as a part of the End Point References of deployed services in the server.
  <HostName>mydomain </HostName>
To use the custom hostname in Carbon management console
<MgtHostName>mydomain</MgtHostName>

2) Next,to change the displaying endpoints per a API from API-Store view, open api-manager.xml file from  
  /repository/conf/ and update the entry which can be found under configuration section as   
  below.

 <APIEndpointURL>http://mydomain>:${http.nio.port},https://mydomain:${https.nio.port}</ 
   APIEndpointURL>

3) Further if you want to change the apps context roots from default values as /store and /publisher to custom values.As an example,let's assume you want to change 'store' app context root from '/store' to '/apistore';
  • navigate to '{APIManager_Home}/repository/deployment/server/jaggeryapps/store/site/conf' and open the site.json file.Change its defined 'context' value as 'apistore' as follows.
  •          "context" : "/apistore"

  • Additionally change the directory name 'store' to 'apistore' from the location '{APIManager_Home}/repository/deployment/server/jaggeryapps'.That's it.Since jaggery apps hot deployment is enabled by default,try to access "http://yourDomain:port/apistore".



Wednesday, September 19, 2012

Creating a JMeter test plan for an API invocation through WSO2 API Manager

The use-case :
  • Create an API for a REST endpoint and publish it from API-Publisher app
  • Then subscribe to it from API-Store app and generate a key
  • Finally create a test-paln from jmeter to this API invocation with using OAuth access token.
Pre-Requesties :


Steps :
  1. Deploy the backend JAX-RS Endpoint    
  • First download and extract above two servers and to run both servers simultaneously,change one server's port offset to 1 by navigating to {Product_Home}/repository/conf/carbon.xml .
  • Then download the sample JAX-RS war file from checking out it from here and deploy it to WSO2 AS -4.1.2  
  • This sample JAX-RS contains three REST endpoints and here I'm going to use its endpoint of getting menu list as '/pizzashack-api-1.0.0/api/menu/'.Once you deployed the war file,you can check accessing   'http://yourip:port/pizzashack-api-1.0.0/api/menu/'  from browser whether you get a successful json response or not.

     2.  Create the API for backend JAX-RS endpoint
  • Browse api-publisher web UI from browser and create a new API with setting its endpoint as  'http://yourip:port/pizzashack-api-1.0.0/api/menu/
Add API
       
  • Publish it to API-Store.
Publish API
     
  • From API-Store,subscribe the created API to an application and generate an access token.So now you are ready to invoke the API.


Subscribe to API
User Subscriptions

     3.  Create JMeter Test Plan
  • Start jmeter with jmeter.sh script and browse jmeter UI. Add a new test-pan.
  • First add a new thread group by navigate to Add->Threads (Users) ->Thread Group  
         


  • Since we are going to send a RESTful[HTTP] request to the create API,click on thread group ,select the   sampler as HTTP Request and add the ip address,port and path accordingly as shown in below image.
          From this example we are doing a GET request.So no need of request parameters.
Add HTTP Request
After setting REST URL for the request
                              
  • Then we need to add the access token for request header.That can be done by adding the config element called 'HTTP Header Manager' to the thread group as below.
Add HTTP Header Manager



  • Then click on 'add' button of the  'HTTP Header Manager' UI and add ;
         header name -"Authorization"
         value            - "Bearer "+accessToken
        
After adding the authorization header

  • Now we have finished configuring test-plan,save all of them and now remaining is running the test-plan.To collect test running results you can add a Listener for thread group as 'View Results Tree' or 'View Results Table' or either graph.Just change number of threads/iterations and see how the average time,other performance values varying on each.
                                        


  • You can find the above created JMeter test plan by checking out it from here.

Monday, September 17, 2012

Connecting WSO2 API Manager with different databases

With WSO2 API Manager GA 1.0.0 release,we have tested it with H2 ,My SQL and Oracle databases.The default database used by API Manager is embedded H2 database.
But in-case if you want to change the database to either other database,following steps have to be followed.

With Carbon 4.0.0 release,it's introduced an unified place to store  all the database data sources related configurations called master-datasources.xml which can be found from {API_Manager_Home}/repository/conf/datasources directory.

Open the 'master-datasources.xml' file and you'll notice there are already defined three datasources as; 

  • WSO2_CARBON_DB-The datasource used for registry and user manager
  • WSO2AM_STATS_DB-The datasource used for getting statistics to API Manager
  • WSO2AM_DB-The datasource used for API Manager database

If you are going to;
  1. Change the database for API Manager 
  • First create a database and run the relevant script which can be found from here,to generate database tables.You can find same scripts under the below location of your extracted APIManager pack.
         {API_Manager_Home}/dbscripts/apimgt
  • Navigate to 'WSO2AM_DB' section of master-datasources.xml file and edit url,username,password and driverClassName accordingly.
  • You can ignore 'validationQuery' entry by removing,if you don't need to validate each query running from the created data-source as it'll effect performance.
  • Remarks:
          If you are going to point 'WSO2AM_DB'  in master-datasources.xml to a mysql database,you  
          need to add its jdbc url configuration as below.         
           
         <url>jdbc:mysql://localhost:3306/APIMANAGERDB?
   
         Note that, you must specify ?autoReconnect=true&relaxAutoCommit=true in the jdbc url.
  • Download the related driver and copy it to {API_Manager_Home}/repository/components/lib folder.
  • Start the server with the parameter -Dsetup as below;
          ./wso2server.sh -Dsetup [or wso2server.bat -Dsetup]
     
    2.  Additionally if you want to change the JNDI lookup datasource name of the datasource used for 
         API Manager
  • Change the entry  <name> under <jndiConfig>  section for the API Manager database in master-datasources.xml file.
  • Then open api-manager.xml and change the  <DataSourceName>  under root entry  <APIManager> as similar value to the above edited jndiConfig name value of master-datasources.xml file.

Wednesday, September 5, 2012

Dealing with SVN Externals

When you are trying to cut a versioned branch from the working trunk directory,an important point that you have to keep on mind is to change the svn externals according to the newly created branch.

SVN Externals

An SVN externals definition is a mapping of a local directory to the URL—and possibly a particular revision—of a versioned resource.In Subversion, you declare externals definitions in groups using the svn:externals property. 

Command to view existing svn externals 

svn propget -R svn:externals .

Command to modify a svn external 

  • If you having one entry as a svn extern property to set on a directory,type below command and then commit it.

svn propset svn:externals 'directory  http://external_url' . property 'svn:externals' set on '.'

  • If you having multiple directory/url pairs as svn externs to set on a directory
Create a file [svnExterns.txt] with putting the individual directory/url pairs.

Then type the below command and commit it.

svn propset svn:externals -F svnExterns.txt .

Command to edit/delete an existing svn externals 

svn propedit svn:externals .

You should see the directory/url pairs will listed after above command.If you want to delete such an extern just remove the specific line and run svn commit command.

Sunday, July 29, 2012

Customizing WSO2 API Store/Publisher App-Part2

From the Part 1 of this tutorial[1], we discussed on overview of API-Store and its directory structure.This tutorial will be focus on the flow of how a user request is handle by API Store web-application front-end and a example to try out.

Browser Request Flow of the API-Store Front-end

Below image will explain the flow of browser request processing happened inside the API-Store jaggery application.Similarily API-Publisher jaggery application will also handle browser requests.
When a user access the API Store/Publisher application through the web-browser,that request will first hit on the relevant page located at 'site/pages' directory in API-Store/Publisher.Then inside that page,to handle the rendering of the web page,it'll call the render() function defined in jagg.jag file resides on location 'jagg/jagg.jag' inside the both applications.

To invoke that render() method,we are passing a json string which contains the base page name,page body layout name and sub layout blocks names[eg:In the below image we have set a sub layout block name called 'api/listing' to be set to the 'middle' section of the layout] and their corresponding inputs.Once render() method invoked by the web page;it first check whether the relevant blocks[in site/blocks directory] and templates[in site/themes/templates directory] for base page,page body layout and for sub layout blocks,exists.

If not processing will stop and rendering of web page also stopped.Else if the relevant blocks and templates exists,inputs passing for the render method(),will retrieved and processed by the relevant blocks and will pass the processed data to the relevant templates.From the relevant templates,html rendering will happened and the user will able to see the reqested web page will rendered in browser properly.

Example

As you got a basic idea of what each directories doing in the API Store web application,now its time to get use of them with an example. To get a better idea of the flow on creating a new web page inside the API-Store application,below steps will explain how to add such a new page to the API-Store inorder to view created APIs per user.Sample code can be found from here.
  1. First Navigate to API-Store web-application code from [1] or simply navigate through the API Manager binary pack as {API Manager Home}/repository/deployment/server/jaggeryapps/apistore.
  2. Then create the page called ‘list-user-apis.jag’ by navigating to ‘apistore/src/site/pages/’ directory.This page will list down the APIs created by logged user for the API-Store.Add the page content as its title,base page,layout,included templates by refering to the file inside the attached sample/page directory.
  3. Then add a url mapping for it in jaggery.conf file in web-application as below;
    "urlMappings":[           {               "url":"/apis/list",               "path":"/site/pages/list-user-apis.jag"  } ]
  4. If you look the attached code sample,since in your added page [list-user-apis.jag],you have defined a template to be included in ‘middle’ part of the layout called ‘list-apis’;Navigate to ‘apistore/src/site/themes/fancy/templates’ and add the directory  ‘list-apis’.
  5. Add a template jag and a initializer jag inside it. Add the html code to template.jag and add imports to javascript files and css relevant to this template into initializer.jag. [You can find the sample code for this template.jag and initializer.jag by navigating to attached sample/templates/list-apis].
  6. Upto now you have completed adding ‘view’ part of your page.Now its time to add the ‘controller’ and ‘model’ part of it.For that add a directory called ‘list-apis’into the directory ‘apistore/src/site/blocks’ of the web-application and add the block.jag inside it.[Note that template and corresponding block directories should named as equal.]
  7. Since you need to output the list of APIs from corresponding template.jag,you can use ‘getOutputs()’ function in block.jag to invoke the relevant method from ‘apistore’ module and return the processed output from block to the template file.[You can find this block from navigating to attached sample/blocks/list-apis.]
  8. The directory ‘apistoreweb/src/module’ contains reference to all the functions plugged through the java module into web-application.
    In above case under ‘api store web/src/module/api/’ directory there’s a jag file called ‘published-by-provider.jag’ which contains the corresponding javascript method [getPublishedAPIsByProvider] which will invoke the required java method from the apistore hostobject for this example.
  9. Thus you don’t need to add a new java method to java module as to plugged into the web-application.But in-case,if you want to add a new java-level method ,first add it to the API-Store/API-Publisher Host Object and then add that method to a jag file inside a subdirectory of the  ‘api store web/src/module/’ directory.And make sure you have defined that method to the ‘module.jag’ in that subdirectory as well.
  10. So now you have done necessary changes to update your change from API-Store web app.Start the API Manager server and navigate to {API Manager Server}/repository/deployment/server/jaggeryapps. Then replace the existing directory ‘apistore’ ,with your changed apistore web app directory.Since exploded mode hot deployment is enabled as default,you can see the changes reflected to web-app UI without restarting the server.
  11. From the browser access “https://ip:port/apistore/apis/list”,then you’ll see the list of published API names by corresponding logged user for the web-app. 
References

Customizing WSO2 API Store/Publisher App-Part1

Up to now,hope most of the audience is familiarized with writing java web applications. Now it's time to write a complete javascript based web application with the help of Jaggery.

Jaggery

Jaggery is a Server Side Javascript Framework to write web-applications and HTTP-focused web services for all aspects of the application:front-end, communication, server-side logic and persistence in pure javascript. It offers a completely javascript way to write all parts of Web applications and services as a way to reduce/eliminate mismatches across different layers of the Web application and API development experience. Such that it provides closing the gap between web apps from web services by allowing one to create both application and APIs at the same time.For more information visit the site [1] ,which contains more information,API documentation and samples of it.

This article will focus on how to write a web application with Jaggery. For that as a real use-case,it'll focus on the implementation of two web applications released with WSO2 API Manager [available with Beta1 version] known as API-Store and API-Publisher.

WSO2 API Manager

WSO2 API Manager is a complete solution for publishing APIs,creating and managing  a developer community and for scalably routing API traffic.Basically it contains with three components called API-Store,API -Publisher and API-Gateway. Out of these three API-Store and API-Publisher are web-applications developed to interact with third party users.Importantly those were bulit as javascript web applications by using Jaggery.For more information on API Manager refer  [2].

Getting Started

Pre-RequestiesWSO2 API Manager

In real world, web applications are not much simple as above. For a web application there are a large number of inter-connected UI pages written using HTML,CSS and Javascript with JQuery or a similar library and the interaction with back-end is happening via form POST,JSON or XML data processing and data storing part done via SQL or a file type.As you can see every step of the process has significant impedance mismatches. This is where Jaggery comes to the spot as its capability of writing all parts of Web applications as a way to reduce/eliminate impedance mismatches across different layers of the Web application and API development experience.
If we pay attention on API Publisher and API-Store web applications,below is the general view of how we have implemented them with the help of jaggery.


Overview

Simply we can separate the story into three components.

1.Back-end Java Implementation [Data Access Layer]

All the API Manager apps related functionalities were written based on a java API as a Data Access Layer and some of the metadata had been stored to WSO2 Governance Registry while final storage kept as database storage.

2.Java Module implementation based on Javascript Hostobjects[3]

As API-Manager related functionalities have been implemented based on a java API and not on a Web Service API,to invoke those back-end java implementations,there was a requirement to plug a java module to interact with both back-end layer[java] and front-end application[javascript]. That's how the two javascript hostobjects named as APIProviderHostObject and APIStoreHostObject were written and mapped the java logic in back-end to the javascript in front-end application.
How we have plugged these two hostobjects to the web-applications in API-Manager product is that,we have defined a module called 'apistore' from these two host objects from a module.xml file which you can found from {API Manager Home}/modules/apistore/module.xml and define two hostobjects inside that module.Sameway you can write your own java modules and plugged as above.

3.Front-end web-app implementation

Front-end web-applications has been written based on jaggery with using HTML,CSS and Javascript and Jquery. For clarity and extensibility purposes,the web-applications have followed Model View Controller pattern. Below shown image is the folder structure of the api-store web app. Note that there's no specific directory structure to create a jaggery app,its upon to you based on the complexity of the app.

API-Store jaggery app directory structure

1) jaggery.conf -This file specifies the application specific configurations. It has used to define the URL-mappings for the pages, define welcome page,security-constraints,etc.
2) site directory -This directory contains below important sub-directories;

  1. Themes- The web-app has the capability of multiple-theme support and easily a user can add a new theme with less customized effort to the app. Currently API-Store app contains two themes called 'fancy' and 'modern'.Each theme contains;     

    • CSS -Contains the stying files of the application.

    • Images-Contains the styling images of the application.

    • js-Contains the globally used JavaScript libraries related files as jquery,bootstrap

    • templates-Contains views of the web-application. The layout of a web page has been separated into layout blocks and each UI of such layout blocks has created using templates. A template can be considered as a re-usable UI block. Inside such a template the rendering HTML for the web UI part and related javaScript event triggering have been included. Note that these templates can be reusable in any page,by including it to the required page. Each template should contain two files as; 

       -template.jag-Which contains the html code.Below is a sample template code.

      <% jagg.template( "api", function(inputs, outputs, jagg) { %>
      //The outputs displaying from the template and the inputs for the template can be via outputs and inputs parameters. 
      //All the htmls included here
       <% }); 
       %>

        -initializer.jag -Which uses to initialize the template by embedding javascript files or css to the template.Below is a sample initializer code. 

      <% jagg.initializer( "api ", {    preInitialize:function (data) {                
       //Below is how to import a javascript and CSS file to a template         
       jagg.addHeaderJS("template", "key", "jsFilePath"); 
      jagg.addHeaderCSS("template", "key", "CSSFilePath");  
       } }); %> 
        

      The layout which is predefined for a web page in API-Store is as below and the templates are set to the each sub layout parts according to the below layout.  


      The basic layout for a web page in API-Store is as above and it can be found with navigating to ‘templates/layout/base/template.jag’.  

      The basic web page template of the app can be found from templates/pages/base/remplate.jag.

      This base page contains the globaly common stylesheets and other related ui library references.

      From a template,you can include another template also by using following code.In current API-Store app you can find such a location from here.

      jagg.includeBlock("nameOfTemplae", inputParamsAsaJson);

       

  1. Blocks -

    This directory can be considered as the Controller part of the web app. User actions on each View(template) are sent to the relevant block and then it handle the incoming HTTP requests.

    Each template has a corresponding block. Handling of incoming HTTP requests done from the jag files included inside directory called ‘ajax’ of each block.A block receives user requests and translates them to actions that the module directory should take from these jag files.Then with the response from module directory,the block selects the appropriate template [view] to pass the response as an input to the template.Below is a sample code of a block.

     

    <%
        jagg.block("api", {
           initializer:function (data) {
           //This initializer function is required when defining a block
           },
         getInputs:function () { //This method is optional,and it can be used to define input                                           //parameters for a block. 
        },
          getOutputs:function(inputs) { //Do some operations from the inputs of the block.  }
        });
        %>

  1. Conf - This directory contains configurations related to web application User Interface. Inside the 'conf' directory,there's a file called site.conf which contains the settings for default theme,site context of the web application.

  1. Pages- This directory contains the main pages that the web-application.This is the intial location comes after a browser request done by a user.

    In a page you can define its titile,what is the basic page and the layout referring from this page,what templates need to add into the page layout and inputs which has to pass into those templates as a json and page will render accordingly using render method of jagg.jag file. Below is a sample code block to render the page with defining its base page,tittle and templates for layouts.

jagg.render({"name":"page/base",
"inputs":{
"title":"API Store Listing",  //Page title
"pagePath":"/site/pages/list-apis.jag", //Page path
"body":[
{
"name":"layout/extended", //Page layout
"inputs":{   //Page inputs
"title":null,
 "middle":{
  "name":"api/listing", //template for the middle
   "inputs":{  //inputs for the template
    "apis":apis
        }
     }
    }
   }
  ]
}
});

3) Module directory 

This can be considered as the 'Model' of the application. It handles the state of the application.When a block invoke an action of a particular module from this directory,it will invoke the relevant function from javascript hostobject.

From jaggery server runtime,it'll process the requests which will go to javascript hostobjects.Then the server will return the response from backend as a mapped javascript object with java response and pass the response again to block and then block will pass the response to corresponding template[view].

4) jagg directory

This is the most important directory of the API-Store web application as it contains the file jagg.jag ,which has kept for handling all functionalities to control and manage interactions among the modules,blocks and templates of the application. It contains custom methods develop for API Store/Publisher web applications to control its functionalities from Jaggery.Some of the important methods defined here is as below

  • jagg.render(obj) -To render the html content for a particular web-page of the application.
  • jagg.getThemePath() -To retrieve the theme defined in 'site/conf/site.json'.
  • jagg.getUserTheme() -To retrieve the user's theme defined in session.
  • jagg.getAbsoluteUrl(path) -To retrieve the absolute path of a relative url .
  • jagg.addHeaderJS(template, key, js) -To import a js file to a given template header .

References

[1] http://jaggeryjs.org

[2] http://wso2.com/products/api-manager/

[3]http://wso2.org/library/tutorials/writing-custom-hostobject

Thursday, July 26, 2012

Validating WSDLs

WSDL: It stands for Web Services Description Language.It's a document written in XML.The document describes a web service.It specifies the location of the service and the operations(or methods) the service expose.
There are two versions of WSDLs as WSDL1.0 and WSDL2.0.This blog post will explain how you can validate those two types of WSDLs

To validate WSDL 1.0 you can get support of WSDL4J library support and it can be done as follow java code snippet.Relevant  wsdl4j API can be found at here.

    javax.wsdl.xml.WSDLReader wsdlReader10 =  
                                          javax.wsdl.factory.WSDLFactory.newInstance().newWSDLReader();
    wsdlReader10.readWSDL(wsdlUrl);

To validate WSDL2.0,you can get support of apache Wooden library and it can be done as following java code snippet.Relevant wooden API can be found  at here.
    
   org.apache.woden.WSDLReader wsdlReader20 
                                  =org.apache.woden.WSDLFactory.newInstance().newWSDLReader();
    wsdlReader20.readWSDL(wsdlUrl);

Once you entered an invalid wsdl url.readWSDL() method will throw an exception and stop reading it fully.
To differentiate WSDL 1.0/WSDL2.0 from your code .you can check wsdl namespace.

Namespace of WSDL1.0: "http://schemas.xmlsoap.org/wsdl/"
Namespace of WSDL2.0: "http://www.w3.org/ns/wsdl"

Thursday, July 19, 2012

Applying a WSDL from a local entry to a proxy service in WSO2 ESB

Local Entry (Local Registry Entry)

The local registry acts as a memory registry where an user can store text strings, XML strings, and URLs. Local entries can be used to hold various configuration elements required by sequences and proxy services. Usually they are used to hold WSDLs, XSDs, XSLT files etc. A local entry can contain XML content as well as plain text content. A local entry can be configured to load content from a remote file too. WSO2 ESB allows to add new local entries easily using user interface configuration

From this blog,I'll explain  how to attach a WSDL to a proxy service from local registry. Note that you can keep a WSDL as a local entry. But it is recommended to keep wsdls in the registry instead, for easier and better management.

Below steps will explainhow to add a WSDL from a local entry to a proxy service.
  1. Extract WSO2 ESB downloaded pack and start it.
  2. Log-in to ESB admin-console.
  3. Create the local entry for WSDL.

  • Navigate to ESB_menu->Manage->Service Bus->Local Entries 


  • Select Add Local Entries option and add the wsdl from In-lined XML Entry option or Source URL Entry option. 
  • After finished adding it,you'll see the local entry is listed in UI.For more information refer the document [1]. 

  1. Create the proxy service 
  • Navigate to ESB_menu->Manage->Add->Proxy Service and select your wanted proxy service template.Here we will select custom proxy template.
           
  • Then for the 'Publish WSDL Options';set 'Publishing WSDL' as 'Pick from registry' as below.


  • To enter 'Reference Key' value click on 'Configuration Registry' link appeared in the UI 
  • Then you will see the Resource Browser UI will pop up.


  • In that Resource Browser UI,on the top you'll see,there's a field called 'Local Registry' with a drop down.



  • Click on the drop down and you'll see the added local entry is listed there as in below image. 
              
  • Select your local entry from this dropdown and click 'Ok' on resource browser UI.Note that please don't picked the path for wsdl from browsing the registry tree.
  • Then proceed with setting endpoints,insequences,outsequences,etc properly to your proxy service.Finally you'll able to successfully create the proxy service. 

How Facebook Orders Your Search Results


When I logged in to Facebook [when I'm free ;)] and tries to search about a friend ,I always notice some names will listed down with a order very fastly.

Have you ever wondered how Facebook orders your search results? Clearly they have some ordering about who they think you are looking for, and they seem to guess pretty well.Facebook order it based on who you interact with, whose profile you look at and who you have recently become friends with.To verify this with a book-marklet ,refer this interesting blog

Monday, June 18, 2012

Introduction to WSO2 API Manager

It has been almost a while after my previous blog post.But I'm sure this blog post will be very useful and important for the audience who are keen of software business world.

What is API Management ?

API Management is a major topic,currently having main discussions and attractions in current software business world which refer as a process of publishing and managing application programming interfaces [APIs]. This have to be achieved through a Software Application known as an API Management Solution.

Why ?

APIs provide a mechanism to extend data,processes and services.Such that from a API Management Solution what we expect is that supporting for collaboration among internal teams as well external partners.

Major Features 

The common tasks associated with the process of API Management includes;
  • Governing access to and usage of APIs
  • Helping developers to discover APIs
  • Metering access and usage of APIs
  • Securing APIS through OAuth support

How WSO2 API Manager fits in 


WSO2 API Manager is the world's First Open Source  API Management Solution.It's ALPHA version release has been announced a while ago and you can download it from  here. While it offers major features expect from a API Management Solution,it consists of major three components.
  • API Gateway
API Manager View
          
          Which is to secure,protect,manage and scale API calls with policy enfrocement.
          Handled By :WSO2 Enterprise Service Bus, WSO2 Governance Registry, WSO2   
          Identity Server
          
  • API Publisher
API Publisher View
          
          Enables API providers to easily publish their APIs, share documentation, provision 
          API   keys, and gather feedback on APIs features, quality and usage.
          Handled By :WSO2 Jaggery, Governance Registry, Identity Server,Business Activity 
          Monitor
  • API Store
        
API Store View
           
          Provides a space for consumers to discover APIs functionality, test APIs online,  
          subscribe to APIs,evaluate them and interact with API publishers.  
          Handled By :WSO2 Jaggery, Governance Registry, Identity Server

                                
Installation  

    Pre-requesties :JDK 1.6 (Sun/Oracle JDK 1.6.0_23 or higher recommended).
Run Samples

     Pre-requesties :Apache Ant 1.8 or higher.
  • Download and extract wso2am-1.0.0-ALPHA.zip
  • Go to 'samples' folder.
  • README.txt inside each of the sample folder provides complete instructions on deploying & testing sample scenarios.
  • To learn how to configure statistics monitoring, read /StatClient/README.txt
 Additional Helpful Links

 You'll find below few blog-posts will be helpful to understand the functionalities of WSO2  
 API Manager.


  Adding to above,there's an up-coming webinar which will be held on 28th of June 2012  
  about   
  Introducing WSO2 API Manager for Complete API Management