How to extend prototyping capabilities of WSO2 API Manager

whats covered: creating API prototypes using mediation policies for APIM 1.10.0

WSO2 API Manager comes with API prototyping capability OOTB. However if you are in need of advance prototyping capabilities or feel restricted by the available implementation for the time being you could tap into the underlying mediation engine (WSO2 ESB) to meet your prototyping need.

1) Create a mediation policy with the prototype logic

The mediation policy should be such that it respond back to the client with configured response rather than passing the message back to the backend. We can achieve this requirement using Respond[1] and Payload Factory mediators[2].

 <sequence xmlns="http://ws.apache.org/ns/synapse" name="prototypesequence">
   <header name="To" action="remove"></header>
   <header name="CustomHeader" scope="transport" value="test123"></header>
   <property name="RESPONSE" value="true"></property>
   <property name="NO_ENTITY_BODY" action="remove" scope="axis2"></property>
   <payloadFactory media-type="json">
      <format>               {"id":"101","name": "dumiduh","desc": "hard coded json"}            </format>
   </payloadFactory>
   <class name="org.wso2.carbon.apimgt.usage.publisher.APIMgtResponseHandler"/>
   <respond></respond>
</sequence>

The example above is using a hard coded response body and headers, you could also populate the response with variables as required[3]. Find the example mediation policy here [4]

 

2) Attach mediation policy to API in flow

Start creating an API with required HTTP methods etc, select Manage API from implementation and from Message Mediation Policies section upload the prototype mediation policy. Publish the API.

3) Invoke

Invoke the API as you would any other managed API.


[1] - https://docs.wso2.com/display/ESB490/Respond+Mediator
[2] - https://docs.wso2.com/display/ESB490/PayloadFactory+Mediator
[3] - https://docs.wso2.com/display/ESB490/PayloadFactory+Mediator#PayloadFactoryMediator-Example3:Addingarguments
[4] -  https://drive.google.com/file/d/0B9oVIeyHJKBXb0xkTGUwSmlJc0E/view?usp=sharing

How to Write a Simple Authentication Handler for an API in WSO2 ESB

whats covered: creating a simple authentication handler for an API in WSO2 ESB 4.8.1

1) Create the Project

Generate the pom file with the required dependencies using WSO2 Developer Studio.

2) Put in the Authentication Logic

In this example the authentication is done based on a per-configured header value in the API request. Find the complete code here[1].

Put the authentication logic inside the handleRequest() method.

....

....

boolean auticationSuccessfull;
        if(!headers.containsKey(TOKEN_HEADER_NAME))
        {
            throw new SynapseException("Access token was not found in the header");
        }
        else
        {
            String token = headers.get(TOKEN_HEADER_NAME).toString();
            if(authenticate(token))
            {
                auticationSuccessfull=true;
            }
            else
            {
                auticationSuccessfull=false;
            }
        }

return auticationSuccessfull;

....

....

private boolean authenticate(String tk)
    {
        //authentication logic
        boolean sentinal=false;
        if(tk.equals("testtoken"))
        {
            sentinal=true;
        }
        if(!sentinal)
        {   
            log.debug("authentication failed for token: "+tk);   
        }
        return sentinal;
    }

....

....

3) Build and Copy the Jar

Drop the jar inside <ESB_HOME>/repository/components/lib

4) Include Handler in the API Configuration

Open up the API configuration with an editor(find it in <ESB_HOME>/repository/deployment/server/synapse-configs/default/api/), Include the handler after the API resource closing tag(at the end of the config) as shown below,

....

....

   </resource>
   <handlers>
      <handler class="com.dumiduh.SimpleAuthenticationHandler"/>
   </handlers>
</api>

[1] - https://drive.google.com/file/d/0B9oVIeyHJKBXY1hZZjBvT1FGQlU/view?usp=sharing

How to Invoke a Shell Script using WSO2 ESB

whats covered: creating a custom mediator to invoke shell scripts for ESB 4.8.1.

1) Create a Mediator Project

Generate a mediator project using WSO2 Developer Studio. Developer Studio Dashboard > Mediator Project.

2) Put in the logic to execute shell scripts

exec() method of the of the current runtime object can be used for this purpose. put the logic inside the mediate method(this method should return true to continue the mediation flow). Find the complete code here[1]

    ...
    ...   
    public String execute()
    {
        StringBuilder output = new StringBuilder();
        Process p;
        try
        {
            p = Runtime.getRuntime().exec(command);
            p.waitFor();
            BufferedReader reader =
                    new BufferedReader(new InputStreamReader(p.getInputStream()));

            String line = "";
            while ((line = reader.readLine())!= null) {
                output.append(line + "\n");
            }
        }
        catch(IOException e)
        {
            e.printStackTrace();
        }
        catch(InterruptedException e)
        {
            e.printStackTrace();
        }

        return output.toString();
    }
    ...
    ...

3) Build and Copy the jar

build the project. Copy the created jar file to <ESB_HOME>/repository/components/lib .

4) Create a proxy service

create a proxy service with the class mediator in the mediation path.

...
...
<inSequence>
<class name="org.wso2.demo.ShellScriptMediator">
      <property name="scriptname"
                value="/home/dumiduh/backup_script.sh"/>
      <property name="scriptparam"
                value="/home/dumiduh/BACKUPS"/>
</class>
<drop/>
</inSequence>
...
...

[1] - https://github.com/handakumbura/ShellScriptMediatorDemo/tree/master

Find more info on the class mediator here,
https://docs.wso2.com/display/ESB481/Class+Mediator

Building WSO2 ESB 4.8.0 from Source

1) create the folders

create folder structure

|---carbon
    |---orbit
    |---kernel
    |---platfrom

orbit contains 3rd party components required by wso2 products, kernal contains the carbon core dependencies required for wso2 products and platform contains the product components them self.

2) checkout source

 

move into orbit and checkout http://svn.wso2.org/repos/wso2/carbon/orbit/trunk/
move into kernel and checkout http://svn.wso2.org/repos/wso2/carbon/kernel/branches/4.2.0/
move into platfrom and checkout http://svn.wso2.org/repos/wso2/carbon/platform/branches/turing/

3) build 

 

build orbit and kernal by moving to the respective folders and keying
mvn clean install -Dmaven.test.skip=true
Since we need to only build ESB open up the pom.xml in platfrom/turing and comment out <module>products</module> and run maven install command(as above).

Move into platfrom/turing/products/esb/4.8.0 and run maven install command.

find the built esb pack in platform/turing/products/esb/4.8.0/modules/distribution/target


Please note that jdk 1.6 is required to build wso2 products.