Requirements
 
Prerequisite knowledge
Basic Knowledge of SOAP Webservice, WSDL document, and REST.
 
User level: All
 
 
 
Required products
  • Adobe ColdFusion Enterprise Edition (2016 release) (Download trial)
 

 
Introduction

Adobe ColdFusion (2016 release) comes with API Manager that helps organization to implement their API strategy faster. The API Manager has many features, one of which is SOAP to REST translation.With this feature, the API manager provides the capability to build REST endpoint for a SOAP web service.
 
The first generation of web service is built on SOAP, a standard protocol based on XML. Unfortunately SOAP is bit heavy weight and requires consumers to write complex clients. To make consumption of a SOAP service easy and convenient, the API Manager provides SOAP to REST translation tool to seamlessly generate REST endpoint for SOAP web services.
 
This article focuses on the example workflow for generating REST endpoint for SOAP web service and then trying it out using TRY-OUT wizard of API Manager.
 

 
Setting up the environment

Install API Manager with ColdFusion 2016. You can either select InVm option or a standalone API Manger. Make sure you select the option to install API Manager. Once API Manager is installed check if the service is running.
 
For development environment, let’s consider that the API Manger portal is running on http://localhost:9000/portal and runtime (proxy) is running on http://localhost:9100/. Ensure that the URLs are accessible from the browser. For this article, we will use a publicly accessible SOAP web service and generate REST endpoint for the same. The WSDL URL for sample SOAP service is http://wsf.cdyne.com/WeatherWS/Weather.asmx?wsdl
 

 
Understanding the components of a WSDL Document

WSDL describes the behavior that a Web service supports by using portTypes. A portType is a collection of operations. Operations are defined in terms of messages. Messages are defined in terms of XML Schema.
 
On a higher level, the WSDL elements are:
 
Element Name
 
Element Description
 
types
 
A container for abstract type definitions using XML Schema.
 
message
 
A definition of an abstract message that may consist of multiple parts, with each part being a different type.
 
portType
 
An abstract set of operations supported by one or more endpoints (commonly known as an interface); operations are defined by an exchange of messages.
 
binding
 
A concrete protocol and data format specification for a particular portType.
 
service
 
A collection of related endpoints, where an endpoint is defined as a combination of a binding and an address (URI).
 
Messages
 
The WSDL message element defines an abstract message that can serve as the input or output of an operation. 
 
<definitions xmlns:s="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/" . . . "> . . . . . <wsdl:message name="GetWeatherInformationSoapIn"> <wsdl:part name="parameters" element="tns:GetWeatherInformation"/> </wsdl:message> <wsdl:message name="GetWeatherInformationSoapOut"> <wsdl:part name="parameters" element="tns:GetWeatherInformationResponse"/> </wsdl:message> <wsdl:message name="GetCityForecastByZIPSoapIn"> <wsdl:part name="parameters" element="tns:GetCityForecastByZIP"/> </wsdl:message> <wsdl:message name="GetCityForecastByZIPSoapOut"> <wsdl:part name="parameters" element="tns:GetCityForecastByZIPResponse"/> </wsdl:message> <wsdl:message name="GetCityWeatherByZIPSoapIn"> <wsdl:part name="parameters" element="tns:GetCityWeatherByZIP"/> </wsdl:message> <wsdl:message name="GetCityWeatherByZIPSoapOut"> <wsdl:part name="parameters" element="tns:GetCityWeatherByZIPResponse"/> </wsdl:message> . . . </definitions>
 
portTypes(Interfaces)
The WSDL portType element defines a group of operations, also known as an interface in most environments. Unfortunately, the term "portType" is quite confusing so use the term "interface" in conversation.
 
In this example for portType WeatherSoap, there are three operations in the wsdl. They are:
 
  • GetWeatherInformation
  • GetCityForecastByZIP
  • GetCityWeatherByZIP
<definitions xmlns:s="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/" . . . "> . . . . . <wsdl:portType name="WeatherSoap"> <wsdl:operation name="GetWeatherInformation"> <wsdl:documentation xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">Gets Information for each WeatherID</wsdl:documentation> <wsdl:input message="tns:GetWeatherInformationSoapIn"/> <wsdl:output message="tns:GetWeatherInformationSoapOut"/> </wsdl:operation> <wsdl:operation name="GetCityForecastByZIP"> <wsdl:documentation xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"> Allows you to get your City Forecast Over the Next 7 Days, which is updated hourly. U.S. Only </wsdl:documentation> <wsdl:input message="tns:GetCityForecastByZIPSoapIn"/> <wsdl:output message="tns:GetCityForecastByZIPSoapOut"/> </wsdl:operation> <wsdl:operation name="GetCityWeatherByZIP"> <wsdl:documentation xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"> Allows you to get your City's Weather, which is updated hourly. U.S. Only </wsdl:documentation> <wsdl:input message="tns:GetCityWeatherByZIPSoapIn"/> <wsdl:output message="tns:GetCityWeatherByZIPSoapOut"/> </wsdl:operation> </wsdl:portType> . . . </definitions>
 
Bindings
The WSDL binding element describes the concrete details of using a particular portType with a given protocol. The binding element contains several extensibility elements as well as a WSDL operation element for each operation in the portType its describing. The binding describes the concrete details for the WeatherSoap portType. The soap:binding element indicates that this is a SOAP 1.2 binding. It also indicates the default style of service (possible values include document or rpc) in this case document along with the required transport protocol (HTTP in this case). The soap:operation element defines the SOAPAction HTTP header value for each operation. The soap:body element defines how the message parts appear inside of the SOAP Body element (possible values include literal or encoded) literal in this case.
 
<definitions xmlns:s="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/" . . . "> . . . . . <wsdl:binding name="WeatherSoap12" type="tns:WeatherSoap"> <soap12:binding transport="http://schemas.xmlsoap.org/soap/http"/> <wsdl:operation name="GetWeatherInformation"> <soap12:operation soapAction="http://ws.cdyne.com/WeatherWS/GetWeatherInformation" style="document"/> <wsdl:input> <soap12:body use="literal"/> </wsdl:input> <wsdl:output> <soap12:body use="literal"/> </wsdl:output> </wsdl:operation> <wsdl:operation name="GetCityForecastByZIP"> <soap12:operation soapAction="http://ws.cdyne.com/WeatherWS/GetCityForecastByZIP" style="document"/> <wsdl:input> <soap12:body use="literal"/> </wsdl:input> <wsdl:output> <soap12:body use="literal"/> </wsdl:output> </wsdl:operation> <wsdl:operation name="GetCityWeatherByZIP"> <soap12:operation soapAction="http://ws.cdyne.com/WeatherWS/GetCityWeatherByZIP" style="document"/> <wsdl:input> <soap12:body use="literal"/> </wsdl:input> <wsdl:output> <soap12:body use="literal"/> </wsdl:output> </wsdl:operation> </wsdl:binding> . . . </definitions>
 
Services
The WSDL service element defines a collection of ports, or endpoints, that expose a particular binding. The basic structure of the service element is as follows:
 
<definitions xmlns:s="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/" . . . "> . . . . . <wsdl:service name="Weather"> <wsdl:port name="WeatherSoap12" binding="tns:WeatherSoap12"> <soap12:address location="http://wsf.cdyne.com/WeatherWS/Weather.asmx"/> </wsdl:port> . . . </wsdl:service> . . . </definitions>
The webservice endpoint address is http://wsf.cdyne.com/WeatherWS/Weather.asmx
 

 
ColdFusion API Manager Workflow for Publisher

A publisher logs into API Manager Publisher Portal in URL http://localhost:9000/portal/#/login
 
Click Create API on the left. On  the Create API page, click Create REST API From SOAP.
 
Create API page
 
file
 
Basic Settings
API Name and Versions are mandatory fields for creating any API. WSDL URL is mandatory for Create REST API From SOAP (SOAP To REST Translation) and Import SOAP API (SOAP Pass Through Proxy)
 
file
Enter the WSDL URL and then click FETCH, which takes you to the SOAP TO REST Mapping Wizard.
 
SOAP To Rest Wizard
 
file
Under Mapping, there are three rows. For this example, work on WeatherSoap, because the SOAP binding uses this portType.
 
  1. Timeout: This is a required field to set timeout between client stubs to the actual service endpoint.
  2. Date Format: This is a required field if the SOAP WEBSERVICE returns date/time as response. The API Manager allows you to enter custom date formats. Supported date formats are MILLISECOND, ISO-8601 and SimpleDateFormat .
 
PortType Mapping
file
In the above image, you have selected the mapping WeatherSoap. The implementation represents the bindings supported for the portType. In this case, SOAP1.1 and SOAP1.2 are present, and you selected WeatherSoapImpl, which is SOAP1.1 binding. You cannot select more than one binding at a time while publishing SOAP TO REST API.
 
The REST Path (WeatherSoap) is the resource path where the converted REST service will be available. This field is editable, you can define your own resource path(REST path)
 
 
Methods
Methods are operations defined in a WSDL Document for a particular portType. Here you can see three operations:
 
  • getWeatherInformation
  • getCityWeatherByZip
  • getCityForecastByZip
In this section you can map individual operation to the REST architecture.
 
file
The RestPath corresponds similarly to the sub resource path in REST Architecture. The value is editable.
 
getWeatherInformation does not take any input arguments and only returns some info. You can enter Produces(Accept header). By default, application/json is populated. You can apply multiple comma-separated accept headers. As the operation does not take any input argument, Consumes(Content-type header) can be kept empty.
 
Type is resource method designator as defined by JAX-RS and corresponds to similarly named HTTP methods. GET, PUT, POST, DELETE are valid types for SOAP TO REST translation.
 
For this operation, keep Type as GET which is default.
 
Moving on to next operation,
 
file
As you can see, this method takes an input argument of type String, in REST translation this value can be passed as QueryParam, PathParam, Form PARAM, and Body.
 
QueryParam means you can call the API as
 
<ApiManagerDomainUrl>/<API Name/Version>/<Method RestPath>/<Method Rest Path>?<Parameter Name>=”Value”
 
http://localhost:9100/ WeatherSoapToRest/v1.0/WeatherSoap/ getCityWeatherByZIP?argo=”value”
 
Parameter Name is the key for QueryParam. You can provide an appropriate key name like CityZipCode.
 
When selecting Param Type as PathParam, make sure you include the Parameter Name in the Sub resource Rest Path, for example, getCityWeatherByZip/{arg0}
 
During invocation of endpoint it becomes:
 
http://localhost:9100/ WeatherSoapToRest/v1.0/WeatherSoap/ getCityWeatherByZIP/ “<cityZipCode>”
 
You can pass the value as FormParam as well, In this case Type should be selected as POST, because form is always posted in body of message. Consumes (Content-type header) should be application/x-www-form-urlencoded.
 
After mapping the Operation/Method, click Generate Rest Endpoints. After this step REST Service endpoint will be created and hosted.
 
file
Apply to all resources check-box is useful in edit work flow where you want to change the old mappings. If you select the check-box and click Generate Rest Endpoints, you will overwrite the previous stubs and REST implementation with the new one. 
 

 
Resources Section

After clicking Generate Rest Endpoints you can see that REST resources have been generated in the Resources section.
 
file
You can review the API and decide what all API’s you want to publish. 
 
file
This section is editable for other workflows of API Manager, but for SOAP this is un-editable. Authentication and SLA can be applied from Authentication and SLA from the left side of the wizard. This settings can be edited here at sub resource level as well.
 
 
Authentication
Select Security->Authentication. The supported authentication types are apiKey, basicAuth, and oAuth2. You can apply any authentication to the REST service generated for SOAP service.
 
For the current example, select apiKey authentication.
 
file
Then click Apply to all resources. You can apply apiKey authentication to all REST resources and sub-resources.
 
 
Endpoints
In this section, you can see the endpoint URL for generated REST service for the input WSDL document.
 
file
For the current example, Swagger Doc is available at this URL:http://localhost:9100/soaptoRest/WeatherSoapToRest/api-docs
 
The URL is a link to Resource Listing doc, and from this doc you can get the URL to API Listing doc, which is in this case is:
 
For details about Swagger Document, you can refer to the Swagger 1.2 specification.
 

 
Publish and Tryout API

file
Once you have provided all the information to create the API, click Publish on the top right corner of the page . After the API is published, Test this API option ppears on the left navigation panel of the page.
 
file
In the tryout screen, you can try out the newly created REST API.
 
 
Try Out
In try out section, you can view the request and response of the API. A wizard guides you through the try-out process.
 
For example, try out getCityWeatherByZip operation. 
 
file
The Parameters table displays about the parameter required to consume the service. In this example arg0 is the argument name, which is of type String, and should be passed to the service endpoint as a QueryParam.
 
arg0 text field you need to pass the zipCode for the city for which you want to get the weather forecast.
 
Produces is the accept header that you can to pass to the REST endpoint. In this case, it is Application/json.
 
Once all the fields are populated, click Run API Call. You can see the API Request Details, Response Details, and Response Body.
 
Request Details
 
In Request Details section, you can see the request URL for this operation, HTTP Method, Accept header sent to the endpoint, and other headers. Params is the QueryParam sent, in this case apiKey=dc88a4f7a7eb46a8bed2da1fea9f17fd and arg0=10008, which you can invoke through:
 
http://localhost:9100/WeatherSoapToRest/v1.0/WeatherSoap/getCityWeatherByZIP?api_key= dc88a4f7a7eb46a8bed2da1fea9f17fd&arg0=10008
 
file
Response Details and Response Body
 
This section contains the response header received from the server. The Response Body contains the response data returned from the endpoint.