Thursday, January 15, 2015

How to invoke APIs in SOAP style in Swagger

WSO2 API Manager has integrated Swagger to allow API consumers to explore APIs through a interactive console which is known as 'API Console'

This swagger based API Console supports invoking APIs i REST style out of the box. So this post going to show how we can invoke APIs in SOAP style in API console of WSO2 API Manager 1.7.0. For that we need to do few extra configurations.

1. Send SOAPAction and Content-Type header in the request
2. Enable sending SOAPAction header in the CORS configuration



First create an API for a SOAP Service. In this example I am using HelloService sample SOAP service of WSO2 Application Server. This HelloService has a operation named greet which accepts a payload as below.


   
   
      
         
         lakmali
      
   


1. Create API



Figure-1 : Design API 


Figure-2 : Implement API by giving SOAP endpoint


Figure-3 :Save and Publish API



2. Update Swagger API Definition


Now we have to edit the default Swagger content and add SOAPAction and Content-Type header. For that go to 'Docs' tab and click 'Edit Content' for API definition.


Figure-4: Edit Swagger API definition

Since we have to send a payload in the request, locate the POST http method in the content. Then add below content into the 'parameters' section of POST http method. 

{
                            "name": "SOAPAction",
                            "description": "OAuth2 Authorization Header",
                            "paramType": "header",
                            "required": false,
                            "allowMultiple": false,
                            "dataType": "String"
                        },
                        {
                            "name": "Content-Type",
                            "description": "OAuth2 Authorization Header",
                            "paramType": "header",
                            "required": false,
                            "allowMultiple": false,
                            "dataType": "String"
                        }


Then the complete POST HTTP method definition would look like below.


Figure-5: Edited Swagger API definition

After doing the above changes Save & Close.

Now if you go to API Store and click on the created API, and the go to API Console, you should see the SOAPAction and Content-Type fields are added to the Swagger UI.


Figure-6: API Console with new header parameters

3. Add New Headers to CORS Configuration


Although we have added required headers, those will be sent in the request oly if they are set as allowed headers in the CORS configuration.

For that open APIM_HOME/repository/conf/api-manager.xml file and locate CORSConfiguration. Then add SOAPAction in to available list of Access-Control-Allow-Headers as below (Content-Type is added by default, So we have to only add SOAPAction). 


Figure-7: API Console with new header parameters

After adding the headers, restart the api manager and invoke the API through API Console. 
When invoking the API, set the SOAPAction according to your SOAP service. Also set the COntent-Type header as 'text/xml'


Figure-8: API Console Invoke API


If you face any issues with swagger invoke, please go through this.

Saturday, December 27, 2014

Multi Tenant API Management with WSO2 API Manager - Part 2




In the previous post we discussed what is multi-tenancy, multi-tenancy in API Development and multi-tenancy in API Store(Consumption). In this post we will be discussing how subscriptions can be managed among multiple tenants, how APIs an be published into different tenant domains, multi-tenancy in API Gateway, multi-tenancy in Key Manager and also multi-tenancy in API Statistics. 

Manage subscriptions among multiple tenants

In the previous post we discussed how different tenants can develop and consume APIs in isolated views of API Publisher and API Store.This section describes how API creators can control who can subscribe to an API. In the Add API page, under Subscriptions you can select the Subscriptions Category.

There are 3 subscription categories.

  1. Available to current Tenant Only

The API will be allowed to subscribe for users in current tenant domain only(tenant domain of API Creator).

  1. Available to All the Tenants

The API will be allowed to subscribe for all the tenants in the deployment.

  1. Available to Specific Tenants

The API will be allowed to subscribe for specific tenants who are mentioned and the current tenant.

Example: UserProfileAPI is an API in hr.com. API developer from hr.com tenant domain set the subscription category of UserProfileAPI to sales.com and eng.com subscribers as below.

figure-6.png


Figure 1 : Subscription availability to specific tenants

Now a Subscriber from eng.com can login to his API Store and then access hr.com API Store. He will be able to subscribe to UserProfileAPI.

Although API subscription can be allowed to different tenant domains, this approach have a drawback. Because API subscribers need to login to own (eng.com) tenant store, then browse hr.com store and discover UserProfileAPI. How can we make UserProfileAPI visible in eng.com Store ? Let’s see in the next section.

Publishing APIs to multiple tenant stores

WSO2 API Manager allows API developers to publish APIs to external stores. BY default, when a tenant user publishes an API, it is getting published in that tenant’s own API Store. With this ‘Publishing to external stores’ feature, each tenant can configure set of external stores that they wish to publish APIs. Then API developers can push APIs to those configured different tenant stores. This allows them to expose APIs to a wider community.

However, when subscribing to such APIs, users will be redirected to original publisher's store.


publish-to-external-stores.png

Figure 2 : Publish to multiple tenant stores

We can configure external stores as below.

1. Login to API Manager management console (https://:9443/carbon) as hr.com admin and select Browse menu under Resources.

resources-browse.png
2. The Registry opens. G o to /_system/governance/apimgt/externalstores/external-api-stores.xml resource.

registry-browse.png

3. Click the Edit as Text link and change the element of each external API store that you need to publish APIs to. 

Example: HR department configure external stores for Sales and Engineering departments as below. So that UserProfileAPI can be pushed into sales.com and eng.com API Stores.  

Figure 3 : External store configuration

figure-9.png

Figure 4 : External API Stores in API Publisher

As shown in the figure 9, hr.com API Publishers can push UserProfileAPI into Engineering Store and Sales Store from the ‘External API Stores’ tab.

Example: admin@hr.com publishes the UserProfileAPI into Engineering Store and Sales Store. When a subscriber from eng.com clicks on UserprofileAPI, there is a link to access original Store.

figure10.png

Figure 5 : UserProfileAPI appearing in eng.com Store

Figure-11.png
Figure 6 : Link to Publisher Store (hr.com store)

Multi-Tenancy in API Gateway

Above we discussed the Multi-Tenant features supported in API Store and API Publisher. There we saw how we can achieve isolation in API development and consumption. Further, how API subscriptions can be managed among tenants and how APIs can be published to different tenant domains were discussed. In this section, let’s look at how Multi-Tenancy is achieved API Gateway and Key Manager level.

In WSO2 API Manager, the API gateway is a simple API proxy that intercepts API requests and applies policies such as throttling and security checks. These API proxies are deployed in WSO2 API Manager as Synapse REST resources. In a multi-tenant deployment, APIs are deployed in tenant isolated manner by having isolated deployment spaces for each tenant. Also APIs are exposed with tenant domain based URL patterns as below.

Example:  We created UserProfileAPI in hr.com domain and ArticleFeeds API in eng.com domain. In the API Gateway these APIs are deployed in different spaces. Also APIs are exposed with tenant domain based URLs with /t/. So as shown in below, UserProfile API is exposed as http://gateway.cin/t/hr.com/userprofile/1.0.0. On the other hand, ArticleFeeds API is exposed as http://gateway.cin/t/eng.com/articlefeeds/1.0.0. Now when Application developers are consuming these APIs from different domains, they’ll see these tenant based API Endpoint URLs.

Figure 7 : Multi-tenancy in API Gateway level

Multi-Tenancy in API Key Manager

The API Key Manager component handles all security and key-related operations. When API Gateway receives API calls, it contacts the API Key Manager service to verify the validity of tokens and do security checks. All tokens used for validation are based on OAuth 2.0.0 protocol. First API subscribers have to create an Application, then subscribe to APIs and generate tokens against that application.
In a multi-tenant deployment, consumer applications are tenant isolated. At the API subscription and key generation, keys (consumer key/secret) are issued against these consumer applications. Then the tenant users, who consume those applications can generate user tokens. Further when storing keys, tenant ids are used to achive tenant separation. This is how mult-tenancy is achieved in API Key Manager.


Multi-Tenancy in Statistics

We can set up WSO2 Business Activity Monitor to collect and analyze runtime statistics from the API Manager. To publish data from the API Manager to BAM, the Thrift protocol is used.
Here, usage data publisher is created per tenant.

Information processed in BAM is stored in a database from which the API Publisher and Store retrieves information before displaying in the corresponding UI screens.
Statistics view in API Store and API Publisher are tenant isolated, since API Store and Publisher apps are tenant isolated. 



Figure 8 : Multi-tenancy in API Statistics

Summary

This post discussed how organizations can collaborate and monetize their APIs across multiple entities such as departments, partners or simply between separate development groups with Multi-tenancy features in WSO2 API Manager. Basically API developers of multiple entities can have isolated views in API Publisher and manage their APIs. Further API consumers correspond to multiple entities can explore and consume APIs from tenant isolated API stores. Moreover this article described how APIs subscriptions can be controlled among tenants and how APIs can be published into multiple API Stores. Finally how multi tenancy is achieved in API Gateway, Key Manager and Statistic were discussed. 







Tuesday, December 23, 2014

Multi Tenant API Management with WSO2 API Manager - Part 1


Introduction


WSO2 API Manager provides a complete solution for API Management. With Multi-tenancy in WSO2 API Manager, organizations can collaborate and monetize their APIs across multiple entities such as departments, partners or simply between separate development groups. 

Why Multi-Tenancy



The goal of Multi Tenancy is, maximizing resource sharing among multiple tenants while providing an isolated view for each tenant.



One of the main benefits of multi-tenancy is the ability to use a single deployment for multiple tenants which lowers the cost and provides better administration. Further this is ideal for  multi departmental and multi-partner type of business settings.



Multi-Tenancy in API Development

WSO2 API Manager provides a simplified Web interface called WSO2 API Publisher for API Design, Implementation and Management. It is a structured GUI designed for API creators to design, implement, manage, document, scale and version APIs, while also facilitating more API management-related tasks such as life-cycle management, monetization, analyzing statistics, quality & usage and promoting & encouraging potential consumers & partners to adopt the API in their solutions.

While providing all these capabilities, WSO2 API Publisher is a tenant isolated application. Meaning, developers from different tenant domains can develop APIs and manage them while having isolated views for each tenant. Let’s look into more details by using a example scenario. 

Example : There is a multi departmental organization in which 3 departments namely HR, Sales and Engineering need to expose their core functionality/services as APIs to internal and external consumption. They are using WSO2 API Manager as the API management solution. So we can consider those 3 departments as 3 tenants in WSO2 API Manager. So that each department can develop and manage their APIs independently.

First we need to create 3 tenants in WSO2 API Manager. Please refer this doc, for tenant creation and listing steps. 

Let’s assume that following tenant domain names are used for each department.


Department Name Tenant Domain
Human Resource hr.com
Sales sales.com
Engineering eng.com


Figure 1 : Tenant Isolated API Publishing for each department

Once you create the tenants, you can login to API Publisher using tenant credentials and design, implement, manage & publish APIs. Find User Guide on API development from here (https://docs.wso2.com/display/AM170/API+Developer+Guide)

Now when tenant users of each domain will have isolated views in API Publisher as below where each tenant have their own view. 

figure-2.png

Figure 2 : hr.com API Publisher view


figure-3.png
Figure 3 : eng.com API Publisher view

Multi-Tenancy in API Store

API Manager provides a structured Web interface called the WSO2 API Store to host published APIs. API consumers and partners can self-register to it on-demand to find, explore and subscribe to APIs, evaluate available resources and collaboration channels. The API store is where the interaction between potential API consumers and API providers happen. Its simplified UI reduces time and effort taken when evaluating enterprise-grade, secure, protected, authenticated API resources.

When there are multiple tenants in the API Manager deployment, there is a tenant isolated view of API store for each tenant domain. In other words there will be a separate store for each tenant.

Public Store and Tenant Stores 

When API Store URL (ex: http://localhost:9443/store) is accessed in a multi tenant deployment, we can see the ‘Public Store’ which is a store of stores.
Public Store is linking to Stores  of all the tenants. For anonymous users, each of this Stores can be browsed. All the Public APIs of each Store will be visible. If one needs to subscribe to APIs, then he should log in to one of the Stores.






figure-4.png




Figure 4 : Public Store linking all the tenant stores

Each of the Stores representing each tenant domain is known as ‘Tenant Store’. It is the tenant isolated API Store of each domain. ex: http://localhost:9443/store?tenant=hr.com

Subscribers from each tenant domain can consume APIs in their tenant store. Let’s look into more details by using an example scenario.

Example: You are a subscriber on hr.com tenant domain. You can first access the Public Store and then visit hr.com Store. Then you can log in to the store with your credentials and consume APIs. Also you can go back to the Public Store and access other Stores as well. But if you want to consume an API in other tenant stores, API developers should allow that. It will be discussed further in “Manage subscriptions among multiple tenants” section in next post. 

figure-5.1.png
figure-5.2.png
Figure 5 : hr.com Tenant Store


So as described above, different tenants can develop and consume APIs in isolated views of API Publisher and API Store. Next post will describe how API creators can control who can subscribe to APIs. 

Tuesday, November 18, 2014

Troubleshooting Swagger issues in WSO2 API Manager

WSO2 API Manager provides this functionality through the integration of Swagger (https://developers.helloreverb.com/swagger). Swagger-based interactive documentation allows you to try out APIs from the documentation itself which is available as the "API Console" in API Store. 

There are certain requirements that need to be satisfied in order to swagger Try-it functionality to work. First requirement is to enable CORS in API Mananger Store. This documentation describes how that should be done. 

But most of them face many issues in getting the swagger Try-it into work. So this blog post describes common issues faced by users with Swagger and how to troubleshoot them.  

Issue-1

API Console keeps on loading the response for ever as below.

Cause -1

API resource not supporting OPTIONS HTTP verb. 

Solution

Add OPTIONS HTTP verb for API resources as below. Then Save the API and Try again. 



Cause -2 

Backend endpoint not supporting OPTIONS HTTP verb. 

Note: You can verify this by directly invoking the backend for OPTIONS verb. If backend is not supporting OPTIONS verb, "403 HTTP method not allowed" will be returned. 

Solution

If you have control over the Backend service/api, enable OPTIONS HTTP verb. 

Note: You can verify this by directly invoking the backend for OPTIONS verb. If backend is supporting OPTIONS verb, 200/202/204 success response should be returned.


If you can't enable OPTIONS HTTP verb in the backend, then what you can do is modify the API synapse sequence of the API, which returns back without sending the request to the backend if it is an OPTIONS request. 

Issue-2

API Console completes request execution, but no response is returned. 


Cause-1

Authentication Type enabled for OPTIONS HTTP verb is not 'None'. 


If this is the cause below error message will be shown in the wso2carbon.log.

org.wso2.carbon.apimgt.gateway.handlers.security.APISecurityException: Required OAuth credentials not provided
at org.wso2.carbon.apimgt.gateway.handlers.security.oauth.OAuthAuthenticator.authenticate(OAuthAuthenticator.java:122)
at org.wso2.carbon.apimgt.gateway.handlers.security.APIAuthenticationHandler.handleRequest(APIAuthenticationHandler.java:92)
at org.apache.synapse.rest.API.process(API.java:285)
at org.apache.synapse.rest.RESTRequestHandler.dispatchToAPI(RESTRequestHandler.java:83)
at org.apache.synapse.rest.RESTRequestHandler.process(RESTRequestHandler.java:64)
at org.apache.synapse.core.axis2.Axis2SynapseEnvironment.injectMessage(Axis2SynapseEnvironment.java:220)
at org.apache.synapse.core.axis2.SynapseMessageReceiver.receive(SynapseMessageReceiver.java:83)
at org.apache.axis2.engine.AxisEngine.receive(AxisEngine.java:180)
at org.apache.synapse.transport.passthru.ServerWorker.processNonEntityEnclosingRESTHandler(ServerWorker.java:344)
at org.apache.synapse.transport.passthru.ServerWorker.run(ServerWorker.java:168)
at org.apache.axis2.transport.base.threads.NativeWorkerPool$1.run(NativeWorkerPool.java:172)
at java.util.concurrent.ThreadPoolExecutor$Worker.runTask(ThreadPoolExecutor.java:895)
at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:918)
at java.lang.Thread.run(Thread.java:662)

Solution

Make the Auth Type as none for OPTIONS HTTP verb as below. Then Save & Publish the API.



Note: If you are seeing the Issue -2 , even though Authentication type is shown as none for OPTIONS, then please re-select the authentication type as 'none' as above. Then Save & Publish the API. There is an UI bug in API Manager 1.7.0, where although you have set some other authentication type other than 'None' for OPTIONS verb, UI shows it as none. 

Cause-2

API Store domain/port which you are currently trying swagger API Console, is not included in the CORS Access-Control-Allow-Origin configuration. For example, in below CORS configuration, only localhost domain addresses are allowed for API Store. But API Console is accessed using IP address. 




Solution

Include domain/port in the CORS Access-Control-Allow-Origin configuration. For above example, we have to include IP address as below.  Then restart the server and try API Console again. 


Issue-3

API Console keeps on loading the response for ever as below when API Store is accessed as HTTPs, while HTTP is working properly. 

Cause-1

Browser blocking the request due to accessing the API Gateway in HTTP from HTTPs. 

Solution

Go to API Publisher and edit "Swagger API Definition" of the API and change the basePath with https gateway address as below. The Save the "Swagger API Definition" and try again. 


Cause-2 

If you are still getting the issue, even after applying the above then, cause can be that the security certificate issued by the server is not trusted by your browser.

Solution

Access the HTTPS gateway endpoint directly from your browser and accept the security certificate. Then try again.