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.

pre-requisites:

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">

   <soapenv:Header/>

   <soapenv:Body>

      <ser:echoString>

            <ser:s>charitha</ser:s>

      </ser:echoString>

   </soapenv:Body>

</soapenv:Envelope>

• 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