Popular Posts

Monday, July 2, 2012

Consuming a SOAP service using WSO2 API Manager

SO2 API Manager is the new kid in the block, the first fully open source API management platform which can be used to create, manage, consume and monitor APIs. WSO2 API manager is based on the award winning SOA middleware platform, WSO2 Carbon thus it inherits the features provided by the modular Carbon platform.
API authors and publishers can publish both REST and SOAP services to external consumers or partners through WSO2 API manager. In this post, we will look in to the steps of publishing and consuming a SOAP based web service using WSO2 API Manager.

Download and install alpha version of WSO2 API Manager from http://dist.wso2.org/products/api-manager/1.0.0-alpha/wso2am-1.0.0-ALPHA.zip. Similar to the other WSO2 Carbon products, you just need to have JDK-1.6.0 or later to run WSO2 API Manager. Then you can just extract the binary and start the server.

Step 1:

We will use a simple SOAP based web service hosted in WSO2 StratosLive Application Server. You can find the WSDL of the service at http://appserver.stratoslive.wso2.com/services/t/superqa.com/Axis2Service?wsdl

Step 2:

WSO2 API Manager consists of three different applications which serve for distinct user requirements. The API Gateway which is accessible through https://localhost:9443/carbon, is used as a gateway for API calls. The API Provider web app is used to publish, manage and monitor statistics of APIs. API provider can be accessed through https://localhost:9443/apiprovider. API Store application acts as the API consumer front end where users can subscribe for the published API. API Store is accessible through https://localhost:9443/apistore Ideally, three different user categories access these three applications. The API gateway is usually hosted and managed by API management provider. Therefore, we can assume that the default admin user of WSO2 API Manager as the API management provider thus he/she initiates creating rest of the user roles in the system. The API provider webapp is usually accessed by people who want to publish and manage new APIs. Therefore, we can think of another distinct role related to creating and publishing APIs. Finally, the API consumer user access API store webapp to subscribe for APIs.

Though we can use the default admin user to access all of the above applications, to be much realistic, lets start to create the roles and users associated to the API provider and API store applications.

  • Log in to API gateway app as admin user (user name=admin, password=admin).
  • Click on Configurein left menu and select Users and Roles
  • Click on Add New Role, enter "publisher" (or whatever you want) as the role name and click on next
  • Select the following permissions from the permission tree

Admin Permissions --> Configure --> Governance
Admin Permissions --> Login
Admin Permissions --> Manage --> API --> publish
Admin Permissions --> Manage --> API --> create
Admin Permissions --> Manage --> Resources --> Govern

  • Click on Finish to complete the creation of new role
  • Now access the Users page and click on Add New User. (say 'charitha' as the user name of new user, password is 'charitha')
  • Assign the above role (publisher) to the new user
We have just created a new user who is granted permissions to access API provider webapp.

Step 3:

Access https://localhost:9443/apiprovider. The log in page of the API publisher application will be launched. Log in to the application using the credentials of the user which we have created in the previous step.
Click on Add menu item in the left navigation pane to add a new API.

Enter the following values for the mandatory fields in the above form.

Name: Axis2ServiceAPI
Context: /SOAPService
Version: 1.0.0
Endpoint URL: http://appserver.stratoslive.wso2.com/services/t/superqa.com/Axis2Service
Tier Availability: Bronze

Leaving the other default values as they are, click on Create to add the new API. The published API will be shown in the All APIs page and it will be in the CREATED state.

Step 4:

The APIs which are at the CREATED state cannot be consumed by any user. Therefore, we need to publish the API to API store. Click on the Axis2ServiceAPI-V1.0.0 in All APIs page which will direct you to the detailed information page of the selected API. Click on Lifecycles tab. Select the state as PUBLISHED. Select Push To Gateway option so that the API will be registered in the API gateway.

Clicking on Update will publish the API. If you see the log of API gateway, you will notice the following message. INFO - API Initializing API: charitha--Axis2ServiceAPI 

Step 5: 

Now, the API which we have created from the SOAP based web service is in PUBLISHED state so that a consumer can subscribe to the API and invoke it. API store can be used for the consumers to subscribe to APIs. Access https://localhost:9443/apistore/. The landing page of WSO2 API Store application will be shown. You will notice the API which just has been published in available in that page.
Click on Signup at the top right corner to register a new consumer user. Enter 'apiconsumer' as the username and 'apiconsumer123' as the password.
Log in to API store using the new consumer's credentials.

Step 6:

Now, we are inside the API Store web application. We should create an application to make API subscriptions and consumption. Click on My Applications tab.
Add a new application with the name, AxisApp as shown below.

We need to generate an OAuth key to consume any API. Click on the Axis2ServiceAPI - 1.0.0 in the API list or left pane of the API Store web application.  Select Axis2App from the Applications dropdown list at the right of the page and click on subscribe.

The "Subscription Successful" confirmation dialog will be popped up. Click on Go to My Subscriptions button to check our new API subscription.

Click on Generate in the above page to create a new API key. Once the key is generated, click on Show Key and copy the API key.

Step 5: Now, we have everything required to consume the API. API has been published to the store, subscribed to the API and possessed an API key. Lets invoke the API using any client. In this example, I will use soapUI, the world's best and most user-friendly web service invocation utility to invoke the API.

  • Create a new soapUI project or use an existing project. 
  • Add the following SOAP request to your soapUI project.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.carbon.wso2.org">

  • Add http://localhost:8280/SOAPService/1.0.0/ as a new endpoint url in soapUI request editor. (This url can be found under the overview tab of Axis2ServiceAPI - 1.0.0 in API store)
  • Add the following HTTP header 
Authorization: Bearer  <Your API key which has been generated when subscribing to the API >
  • Now, your soapUI request editor will be similar to the following.

  • Submit the request and check the response. Since we have subscribed under bronze tier, you will be allowed to send 1 request per minute



Nice article, anyway i just curious to know how this statistics things getting published cos,when i in api provider statistics come up with "No data found. Check BAM server connectivity..."

Charitha said...

In order to retrieve the statistics, we need to plug a BAM server to API manager. Will publish another post on how to configure BAM with AM soon.


Siva Sivasuthan said...

Good work guys,

I would like to know how API Manager handles the scalability in cloud environment.


Cathy said...

Very helpful! Most API management platforms are paid. I hope the scenario is going to change after WSO2's introduction. One thing I'd like to know, did it undergo quality assurance testing and where the report was produced?

Asanka said...

Awesome post Charitha, you have written exactly what I was looking today.
Last week I had to do a on-the-fly demo on WS-Discovery. I just google with following content "WSO2 WS-Discovery Charitha" because I the content you publish is accurate and to the point, demo did work and I got a big hand from the audience.
- Asanka

Charitha said...

Thanks a lot for the comment Asanka :)

riccardo said...

How do I "Add the following SOAP request to your soapUI project." in soapUI? I can't see any option to do it..thanks

Charitha said...

You can add a SOAP request test step to an existing test suite in soapUI. Then copy and paste the given SOAP envelope there. See http://www.soapui.org/Functional-Testing/functional-testing.html

riccardo said...

Hi, I have downloaded the new version of API Manager 1.0.0 GA. In the Store I can now see new keys: Access Token, Consumer Key, Consumer Secret, what are the related benefits? Also I am confused about publishing the WSDL, since that has not a related API KEY, so everyone can access it. For that reason i have tried to add access token from ESB, but that will not authenticate the API Manager's Users (like Apisubscriber). So, is there a way to create an API key for WSDLs as well from the API Manager? many thanks, great articles.
Best wishes

Mike said...

Can you connect the API manager to the Identity Server so there is only one user database?

Wolfgang said...

I downloaded API MAnager 1.8 and can not follow your tutorial in any way. Do the newer versions only allow to publish REST APIs?


Charitha said...

I no longer work at WSO2 hence I'm not in a position to explain the latest versions of their middleware. Please raise this question in stackoverflow so that a wso2 engineer will answer.