This post explains how we can publish an existing SOAP service as a REST API using
WSO2 API Manager.
We will be using a sample data-service called "OrderSvc"as the SOAP service which can be deployed as a SOAP service in
WSO2 Data Services Server. But this could be any of SOAP service.
1. Service Description of ‘OrderSvc’ SOAP Backend Service
This “orderSvc” service provides WSDL with 3 operations (“submitOrder”, “cancelOrder”,
“getOrderStatus”).
submitOrder operation takes ProductCode and Quantity as parameters.
Sample request :
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:dat="http://ws.wso2.org/dataservice">
<soapenv:Header/>
<soapenv:Body>
<dat:submitOrder>
<dat:ProductCode>AA_1</dat:ProductCode>
<dat:Quantity>4</dat:Quantity>
</dat:submitOrder>
</soapenv:Body>
</soapenv:Envelope>
cancelOrder operation takes OrderId as parameter and does an immediate cancellation and returns a confirmation code.
Sample request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:dat="http://ws.wso2.org/dataservice">
<soapenv:Header/>
<soapenv:Body>
<dat:cancelOrder>
<dat:OrderId>16</dat:OrderId>
</dat:cancelOrder>
</soapenv:Body>
</soapenv:Envelope>
orderStatus operaioin takes the orderId as parameter and return the order status as response.
Sample request :
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:dat="http://ws.wso2.org/dataservice">
<soapenv:Header/>
<soapenv:Body>
<dat:orderStatus>
<dat:OrderId>16</dat:OrderId>
</dat:orderStatus>
</soapenv:Body>
</soapenv:Envelope>
We need to expose this "OrderSvc" SOAP service as a REST API using API Manager. And once we exposed this as a REST API, “submitOrder”, “cancelOrder”, “getOrderStatus” operations should map to REST resources as bellow which takes the user parameters as query parameters.
“/submitOrder” (POST) => request does not contain order id or date; response is the full order payload.
“/cancelOrder/{id}” (GET) => does an immediate cancellation and returns a confirmation code.
“/orderStatus/{id}” (GET) => response is the order header (i.e., payload excluding line items).
Deploying the Data-Service :
1.
Login to the MySQL and create a database called “demo_service_db” .
(This database name can be anything , we need to update the data-service
(.dbs file) accordingly).
mysql> create database demo_service_db;
mysql> demo_service_db;
2. Execute the dbscript given here
on the above created database. This will create two tables
‘CustomerOrder’, ‘OrderStatus’ and one stored procedure ‘submitOrder’.
Also it will insert some sample data into two tables.
3. Include mysql jdbc driver into DSS_HOME/repository/components/lib directory.
4. Download the data-service file given here.
Before deploy this .dbs file, we need to modify the data source section
defined in it. i.e in the downloaded orderSvc.dbs file, change the
following properties by providing correct jdbcUrl ( need to point to the
database that you created in step 1) and change the userName/ Pwd of
mysql connection, if those are different than the one defined here.
<config id="ds1">
<property name="driverClassName">com.mysql.jdbc.Driver</property>
<property name="url">jdbc:mysql://localhost:3306/demo_service_db</property>
<property name="username">root</property>
<property name="password">root</property>
</config>
5.
Deploy the orderSvc.dbs file in Data services server by copying this file
into “wso2dss-3.2.1/repository/deployment/server/dataservices”
directory. Start the server.
6. Before expose through API Manager, check whether all three operations works as expected using try-it tool or SOAP-UI.
submitOrder
Sample request :
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:dat="http://ws.wso2.org/dataservice">
<soapenv:Header/>
<soapenv:Body>
<dat:submitOrder>
<dat:ProductCode>AA_1</dat:ProductCode>
<dat:Quantity>4</dat:Quantity>
</dat:submitOrder>
</soapenv:Body>
</soapenv:Envelope>
Response :
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<submitOrderResponse xmlns="http://ws.wso2.org/dataservice">
<OrderId>16</OrderId>
<ProductCode>AA_1</ProductCode>
<Quantity>4</Quantity>
</submitOrderResponse>
</soapenv:Body>
</soapenv:Envelope>
cancelOrder
Sample request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:dat="http://ws.wso2.org/dataservice">
<soapenv:Header/>
<soapenv:Body>
<dat:cancelOrder>
<dat:OrderId>16</dat:OrderId>
</dat:cancelOrder>
</soapenv:Body>
</soapenv:Envelope>
Response:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<axis2ns1:REQUEST_STATUS xmlns:axis2ns1="http://ws.wso2.org/dataservice">SUCCESSFUL</axis2ns1:REQUEST_STATUS>
</soapenv:Body>
</soapenv:Envelope>
orderStatus
Sample request :
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:dat="http://ws.wso2.org/dataservice">
<soapenv:Header/>
<soapenv:Body>
<dat:orderStatus>
<dat:OrderId>16</dat:OrderId>
</dat:orderStatus>
</soapenv:Body>
</soapenv:Envelope>
Response:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<OrderStatus xmlns="http://ws.wso2.org/dataservice">
<OrderStatus>CANCELED</OrderStatus>
</OrderStatus>
</soapenv:Body>
</soapenv:Envelope>
2. Configuring API Manager
1. Download the custom sequence given here
and save it to the APIM registry location
“/_system/governance/apimgt/customsequences/in/”. This can be done by login to the API Manager carbon management console.
In the left menu section, expand the Resources -> Browse -> Go to "/_system/governance/apimgt/customsequences/in" -> Click in "Add Resource" -> Browse the file system and upload the "orderSvc_supporting_sequence.xml" sequence that downloaded above. Then click "Add". This step will save the downloaded sequence into registry.
4. Create orderSvc API by wrapping orderSvc SOAP service.
Login to the API Publisher and create a API with following info.
Name: orderSvc
Context: ordersvc
Version: v1
Resource definition1
URL Pattern: submitOrder
Method: POST
Resource definition2
URL Pattern: cancelOrder/{id}
Method: GET
Resource definition3
URL Pattern: orderStatus/{id}
Method: GET
Endpoint
Type:* : Select the endpoint type as Address endpoint. And go to the
“Advanced Options” and select the message format as “SOAP 1.1”.
Production Endpoint:https://localhost:9446/services/orderSvc/ (Give the OrderSvc service endpoint)
Tier Availability : Unlimited
Sequences : Click on the Sequences checkbox and selected the previously saved custom sequence under “In Flow”.
Publish the API into gateway.
We are done with the API creation.
Functionality of the custom sequence "orderSvc_supporting_sequence.xml"
OrderSvc backend service expecting a SOAP request while user invoking API by sending parameters as query parameters (i.e cancelOrder/{id}, orderStatus/{id}).
This custom sequence will take care of building SOAP payload required for cancelOrder, orderStatus operations by looking at the incoming request URI and the query parameters.
Using a switch mediator, it read the request path . i.e
<switch xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope" xmlns:ns3="http://org.apache.synapse/xsd" source="get-property('REST_SUB_REQUEST_PATH')">
Then check the value of request path using a regular expression and construct the payload either for cancelOrder or orderStatus according to the matched resource. i.e
<case regex="/cancelOrder.*">
<payloadFactory media-type="xml">
<format>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header/>
<soapenv:Body xmlns:dat="http://ws.wso2.org/dataservice">
<dat:cancelOrder>
<dat:OrderId>$1</dat:OrderId>
</dat:cancelOrder>
</soapenv:Body>
</soapenv:Envelope>
</format>
<args>
<arg evaluator="xml" expression="get-property('uri.var.id')"/>
</args>
</payloadFactory>
<header name="Action" scope="default" value="urn:cancelOrder"/>
</case>
<case regex="/orderStatus.*">
<payloadFactory media-type="xml">
<format>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header/>
<soapenv:Body xmlns:dat="http://ws.wso2.org/dataservice">
<dat:orderStatus>
<dat:OrderId>$1</dat:OrderId>
</dat:orderStatus>
</soapenv:Body>
</soapenv:Envelope>
</format>
<args>
<arg evaluator="xml" expression="get-property('uri.var.id')"/>
</args>
</payloadFactory>
<header name="Action" scope="default" value="urn:orderStatus"/>
</case>
Test OrderSvc API published in API Manager
Login to the API Store and subscribe to the OrderSvc API and generate a access token. Invoke the orderStatus resource as given bellow. This will call to OrderSvc SOAP service and give you the response.
curl -v -H "Authorization: Bearer _smfAGO3U6mhzFLro4bXVEl71Gga" http://localhost:8280/order/v1/orderStatus/3
