WSO2 API Manager Introduction-1

WSO2 API Manager is a complete solution for publishing APIs, creating and managing a developer community and for scalably routing API traffic. It leverages proven, production-ready, integration, security and governance components from the WSO2 Enterprise Service Bus, WSO2 Identity Server, andWSO2 Governance Registry. In addition, as it is also powered by the WSO2 Business Activity Monitor, the WSO2 API Manager is ready for massively scalable deployment immediately. Here in this post i will briefly describe key functionalities and terms in WSO2 API manager.

API Gateway
This is responsible for securing, protect, manage, and scale API calls. The API gateway is a simple API proxy which intercepts API requests and applies policies such as throttling and security checks. It is also instrumental in gathering API usage statistics. We are using set for handlers to security validation and throttling purposes.  It will pass web service call to actual back end after these validation steps. If it is token request call then directly pass to keymgt server to handle it. We can add remove these handlers using source view of synapse configuration. When it comes to production deployments this server hits higher number of requests as all api calls goes through this server. So we have to handle this very carefully. Fine tuning and additional configuration changes according to environment is must to achieve highest performance

API Publisher
This enables API providers to easily publish their APIs, share documentation,provision API keys, and gather feedback on APIs features, quality and usage. You can create new apis by pointing to actual back end service and also define rate limiting policies available for this api.
Here are the some of publisher features.
Create, manage API and publish them to gateway.
Monitor API consumers, behaviour, response time, last accessed time and etc.
List the active subscriptions per each API.
Manage life cycles versions and policies. Based on the state of API you can set it to any of following state.

CREATED: API metadata has been added to API store, but it is not visible to subscribers
yet, nor deployed to the API gateway

PUBLISHED: API is visible in API store, and eventually ( if the “Push to Gateway” option is selected at publishing time)

DEPRECATED: API is still deployed into API gateway (available at runtime to existing users) but not visible to subscribers. An API can automatically be deprecated when a new version is published.

RETIRED: API is not unpublished from the API gateway and retired.

BLOCKED: Access is temporarily blocked.

API Store
Provides a space for consumers to self-register, discover APIs functionality, subscribe to APIs, evaluate them and interact with API publishers. Here users can come and view existing apis created and self sign in. After that they can create their own application by bundle multiple apis together to one application. Once user creates application he can generate 3 type of keys.
Application Token - This is security token that can use to call created application API’s
Consumer key, Consumer secret key – These key pair can use to generate a new access token for given application and user.
Later we will see how we can use these key to make actual API call. Here are the feature list for API store.
View top used, new featured APIs and search by name, tag or creator.
API rate, share comments, feature requests and participate forum discussions.
Create, manage application, add remove APIs to application.
Generate application keys consumer and consumer secret keys for application.
Download help and documents contact owners of API and ask questions.
Self-signup for API consumption.

API Key Manager Server
This is responsible for all security and key related operations. Normally when gateway hits API call it calls keymgt service and verify the validity of token provided. And if gateway gets login call it directly forward it to keymgt server. If we discuss little bit about this login call its basically use for get a new access token. So for this we have to pass user name, password, consumer key and consumer secret key you got when you register your application. All tokens use for validation are based on OAuth 2.0.0 protocol.  All secure authorization of APIs is provided using the OAuth 2.0 standard for key management. The API gateway supports API authentication with OAuth 2.0, and it enables IT organizations to enforce rate limits and throttling policies for APIs by consumer.


There are 3 types of users we can consider in API story. Here are those. These roles are based on the privileges they have and tasks they perform.

Creator( The technical owner of an API)
A creator will typically be a person in a technical role who understands the technical aspects of the API (interfaces, documentation, versions, how it will be exposed by API gateway) and uses the API publisher web application to provision APIs into the API store. The creator will use the API store to consult ratings and feedback provided by API users. Creator can add APIs to the store but cannot manage their lifecycle

Publisher( The business owner of an API)
The publisher typically manages a set of APIs across the enterprise or business unit and controls the API lifecycle and monetization aspects. The publisher is also interested in usage patterns for APIs and as such has access to all API statistics.

Consumer(The developer or consumer of an API)
the consumer uses the API store to discover APIs, consult the documentation and forums as well as rate/comments on the API. He/she subscribes to APIs to obtain an API key. Consumers can bundle multiple API’s together into one application and use it. Actual application consumers are user devices it may be computer application or mobile application.
See the following diagram to understand this concept clearly.

How to enable/disable cache for API Key validation information and JWT token in 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. It leverages proven, production-ready, integration, security and governance components from the WSO2 Enterprise Service Bus, WSO2 Identity Server, and WSO2 Governance Registry. In addition, as it is also powered by the WSO2 Business Activity Monitor, the WSO2 API Manager is ready for massively scalable deployment immediately.

According to wiki cache is a mechanism for the temporary storage (caching). So we use cache in WSO2 products to achieve higher performance. Please refer my previous article on replicate caching of API manager. So if we did a distributed deployment based on requirement we can decide whether we keep key validation information cache in gateway side or keymgt side. If you deployed both nodes in same data centre and do not worry about network overhead added you can keep cache at keymgt side. Else you can keep cache in gateway side. This is the best way of doing this since it prevents additional web service call. Lests see how we can configure it from gateway side.
Add the following lines under tag in api-manager.xml found under /repository/conf.

<EnableGatewayKeyCache>false</EnableGatewayKeyCache>

So above configuration will disable API gateway side ley validation information cache. Then it will call to keymgt per each incoming request.

Also we can cache JWT token with api key validation information. We can do this in keymgt node. Lets see how we could do this. This is also important as JWT generation is bit costly operation.
Add the following lines under tag in api-manager.xml found under /repository/conf.

<EnableJWTCache>false</EnableJWTCache>

So above configuration disable JWT cache which means generate new JWT token per each call to keymgt server.

How to add user claims as custom header of login response of 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. It leverages proven, production-ready, integration, security and governance components from the WSO2 Enterprise Service Bus, WSO2 Identity Server, and WSO2 Governance Registry. In addition, as it is also powered by the WSO2 Business Activity Monitor, the WSO2 API Manager is ready for massively scalable deployment immediately.

Sometimes users may want to get some user claims as response headers of login call response message. Let say if you have your own implementation of JDBC User store manager you might have different user claims. So here we will see how we can use configurations to retrieve them as headers. This is bit complex use case which might not use by each and every one. I did this post because we support this feature and for my future reference.

In the identity.xml add following section (with the claims you need)

<OAuth>.....</OAuth>

When you define the claim - DisplayName will appear as the HTTP Header name in the response.

<RequiredRespHeaderClaimUris>
<ClaimUri>http://wso2.org/claims/emailaddress</ClaimUri>
<ClaimUri>http://wso2.org/claims/gender</ClaimUri>
 </RequiredRespHeaderClaimUris>

 Send curl request as follows :
curl -v -X POST -H "Authorization: Basic Z3pidExIS3NsTVU2dm82dXVmZExcvxcvcZDRU9ZYTpkUzFydFRSWjlVMnIwX241bzkyRk9WTlpldFVh" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -d "grant_type=password&username=admin&password=admin" http://localhost:8280/login/

This is the response.
< HTTP/1.1 200 OK
< Content-Type: application/json;charset=UTF-8
< Cache-Control: no-store
< Email: test@test.com
< Gender: male
< Pragma: no-cache
< Server: WSO2 Carbon Server
< Date: Wed, 12 Sep 2012 09:54:30 GMT
< Transfer-Encoding: chunked

How to use clustering and replicating cache to improve performance and high availability of WSO2 API Manager

Performance is very critical factor when it comes to real product deployments. So most of use use cache to avoid unnecessary web service calls database calls. In WSO2 API Manager api gateway is the most critical thing if we consider performance. In real production systems we separate api manager in to several parts based on their functionalities.
01. API Gateway (All api calls hits gateway validation throttling happen here)
02. API Keymgt (Security validation part)
01. API Store (Allows users to subscribe apis / allow self registrations)
01. API Publisher (Allow publishers to create and publish new API's)
01. API Registry (Control registry)

So as you see API Gateway hits all inbound calls to apis. So most of production systems we recommend users to have 2 nodes clustered instead having one node. In this case you have to configure load balancer carefully to distribute load between both nodes. If you are using F5 like hardware load balancer make it session aware to get optimum performance and if you are using WSO2 Elastic Load Balancer it will take care of session awareness as well as service awareness for you. Both nodes should share same configurations and db and most importantly cache and carbon context. Because carbon context carries throttling related sensitive information. Also we use cache to cache keys to avoid unnecessary web service calls.

So first we will we how to enable clustering for nodes. Replace clustering section in repository/conf/axis2/axis2.xml with following configuration.

<clustering class="org.apache.axis2.clustering.tribes.TribesClusteringAgent" enable="true">
        <parameter name="AvoidInitiation">true</parameter>       
        <parameter name="membershipScheme">multicast</parameter>
        <parameter name="domain">wso2.carbon.domain</parameter>
        <parameter name="synchronizeAll">true</parameter>
        <parameter name="maxRetries">10</parameter>
        <parameter name="mcastAddress">228.0.0.4</parameter>
        <parameter name="mcastPort">45564</parameter>
        <parameter name="mcastFrequency">500</parameter>
        <parameter name="memberDropTime">3000</parameter>
        <parameter name="localMemberPort">4000</parameter>
        <parameter name="preserveMessageOrder">true</parameter>
        <parameter name="atmostOnceMessageSemantics">true</parameter>
        <parameter name="properties">
      <property name="backendServerURL" value="https://${hostName}:${httpsPort}/services/"/>
        <property name="mgtConsoleURL" value="https://${hostName}:${httpsPort}/"/>
        </parameter>
        <groupManagement enable="false">
       <applicationDomain name="apache.axis2.application.domain"
      description="Axis2 group"
     agent="org.apache.axis2.clustering.management.DefaultGroupManagementAgent"/>
        </groupManagement>    
        <nodeManager class="org.apache.axis2.clustering.management.DefaultNodeManager"
                     enable="true"/>  
        <stateManager class="org.apache.axis2.clustering.state.DefaultStateManager"
                      enable="true">
            <replication>
                <defaults>
                    <exclude name="local_*"/>
                    <exclude name="LOCAL_*"/>
                </defaults>
                <context class="org.apache.axis2.context.ConfigurationContext">
                    <exclude name="local_*"/>
                    <exclude name="UseAsyncOperations"/>
                    <exclude name="SequencePropertyBeanMap"/>
                </context>
                <context class="org.apache.axis2.context.ServiceGroupContext">
                    <exclude name="local_*"/>
                    <exclude name="my.sandesha.*"/>
                </context>
                <context class="org.apache.axis2.context.ServiceContext">
                    <exclude name="local_*"/>
                    <exclude name="my.sandesha.*"/>
                </context>
            </replication>
        </stateManager>
    </clustering>

Do this for both nodes. Refer  this article on cluster configurations if you need more information.

Now we need to enable replicate cache between two nodes.

1.In your setup caching synchronization should be done based on a predefined multicast ip and a port.
The caching synchronization is done by Jgroups multicasting - and you can specify a port and the address if needed as system properties by updating wso2server.sh.

-Djgroups.udp.mcast_addr="224.10.10.10" \
-Djgroups.udp.mcast_port="5555" \

Add following configurations to repository/conf/etc/cache.xml

<configuration>
        <clusterName>apimanager-cache</clusterName>
        <cacheMode>replicated</cacheMode>
        <sync>true</sync>
        <l1>
            <enabled>true</enabled>
            <lifespan>60000</lifespan>
        </l1>
    </configuration>

2. Specify valid<HostName>in carbon.xml
3. If you do not want to replicate user-core caches among nodes, add unique cache identifiers for each node as a child under the corresponding

<UserStoreManager>

(JDBCUserStoreManager or AD) of user-mgt.xml

<Property name="UserCoreCacheIdentifier">node2</Property>

i.e:- Since we use separate user stores for publisher and store, user-store caches should not be replicated among those nodes. Hence, we can add two different cache identifiers for each publisher and store nodes.
In store:

<UserStoreManager class="org.wso2.carbon.user.core.jdbc.JDBCUserStoreManager">
<Property name="UserCoreCacheIdentifier">node2</Property>

In publisher:

<UserStoreManager class="org.wso2.carbon.user.core.ldap.ActiveDirectoryUserStoreManager">
<Property name="UserCoreCacheIdentifier">node1</Property>

4. Start servers with -Dbind.address= system property

Repeat same for other node as well. If you done configurations propery you will see cluster joining messages in output log of api gateway nodes as follows.

[2012-09-04 16:22:39,265]  INFO - TribesMembershipListener New member 192.168.115.218:4000(wso2.carbon.domain) joined cluster.

[2012-09-04 16:22:41,061]  INFO - TribesClusteringAgent Local Member 192.168.115.218:40(wso2.carbon.domain)

[2012-09-04 16:22:41,062]  INFO - TribesUtil Members of current cluster

[2012-09-04 16:22:41,062]  INFO - TribesUtil Member1 192.168.115.218:4000(wso2.carbon.domain)

If you enabled logs for jgroup you will see following messages as well.

[2012-09-04 16:22:27,278]  INFO - JGroupsTransport ISPN000094: Received new cluster view: [sanjeewa-TECRA-M11-23170|2] [sanjeewa-TECRA-M11-23170, sanjeewa-TECRA-M11-37541, sanjeewa-TECRA-M11-17759]

Please note that keeping other configurations as default is fine. But you have to configure gateway, store, publisher, registry, keymgt in a way they aware about each others. With this type of deployment you will be able to achieve great performance. To fine tune API gateway node please refer my previous blog post which describe how improve response time of api calls.