We recently had a client requirement to demonstrate a proof of concept (PoC) using RAML/APIKit and Data mapper to integrate with an existing SOAP API in CloudHub. The Web Service Consumer, which is provided by MuleSoft, has frontend JSON over HTTP APIs that integrates with backend functionality exposed by SOAP APIs from CloudHub. In this article, I will take you through a reverse engineering process that I had to go through to make the Web Service Consumer example a RAML based API using APIKit. At the end of this article, you can get complete code of this PoC from a Github repository. Also, a link to the APIKit Console for the source code of this article, which is deployed to CloudHub, is provided.
- You have reviewed and understood the Web Service Consumer example.
- You have basic working experience with RAML, APIKit and DataMapper
- The source code of this article is tested on the following environment:
- Anypoint Studio 5.1.2
- Apache Maven 3.1.1
- Mule Runtime 3.6.1 EE both on standalone server and CouldHub
- Note: Do not use 3.6.2 EE. As of writing this article, the ApiKit 1.6.1 still is not compatible with 3.6.2 EE
- Mule Module APIKit 1.6.1
What has been reversed engineered?
In the example of Web Service Consumer, the following changes have been made:
- A new mule project in which "ApiKit Settings" is enabled created.
- In api.raml file, the resource API for creating an order and fetching inverntory list defined.
- The following two schemas which are refencred from api.raml file added under src/main/api/schemas:
- There are two flows created which correspond to creating an Order using POST and fetching inventory list using GET operations.
- Data mapper files are re-created using datamapper tool as follows:
- For creating order, the src/main/api/example/order-example-in.json is mapped to XML envelope in SOAP payload
- For fetching inventory list, the ListInventoryResponse is mapped to src/main/api/example/inventory-example-out.json
- HTTP Response builders are not used anymore
- HTTP In bound endpoint are not used anymore
- http.status is deleted after calling Order Tshirt SOAP Service since in the RAML definination we have specified status code of 201 for order creation. If we do not delete http.status, the http.status code of 200 would have been propogated from out bound property of Orde Tshirt service to the client code.
- An out bound property "Location" which corresponds to Location in api.raml is also set from an Id of order. The "Location" is passed to the client code as HTTP header.
Figuire 1.0 illustrates a flow using APIKit that exposes inventory list in JSON from a SOAP API which is hosted on a CloudHub. This flow can be compared with "ListInventory Flow" in Web Service Consumer example.
Figuire 2.0 illustrates a flow using APIKit that exposes creating an order from a JSON payload to a SOAP API which is hosted on a CloudHub. This flow can be compared with "OrderTshirt Flow" in Web Service Consumer example.
In this article, we have shown you how you can turn your existing JSON over HTTP APIs into a formal JSON APIs using RAML and APIKit. If you compare the two new flows with original Web Service Consumer example, you would notice that HTTP in bound connectors and response builders are not used anymore. Also, if you browse the code in webservice-consumer-raml.xml file, you would notice that HTTP in bound connector is replaced with HTTP listener.
The source code of this article has been deployed to CouldHub. You can click on APIKit Console to navigate RAML API definition for these two Rest endpoints. Also, you can retrieve list of inventories in JSON formats by clicking on Get Inventory List. When you click on Get Inventory List, you are sending a request to "inventory" RAML API which delegates that request to "ListInventory" SOAP API for fetching inventory list.
The entire source code of this article can be found in Github.