SOAP API to REST with Azure API Management and Visual Studio Code

A SOAP WSDL (Web Service Description Language) is an XML-based interface description language that is widely used by older APIs. With the modernization of Web standards, most APIs today use REST (Representational state transfer) and JSON (JavaScript Object Notation).  In some cases, there may be a need to convert a SOAP API to REST without having to refactor the API. Luckily for us, Web development tools and Azure can help us get this done.

Azure API Management Service

With the evolution of Web tooling and Cloud computing, we can continue to use SOAP APIs by importing a WSDL definition and creating an OpenAPI (JSON) definition using Visual Studio Code (VS Code) and Azure API Management service. Let us see how we can quickly do this.

We first need to open VS Code and have an Azure subscription. We can get a free Azure subscription by visiting azure.com. Once VS Code is running, we need to install the Azure API management extension from the extension’s menu.  This extension enables us to connect to Azure and provision new API services.

From the Azure API Management extension menu (Azure Icon – Left Bar), select the target subscription. Resources need to be created under a subscription. Right click and select Create “API management in Azure”.  This action opens an edit box on VS Code command palette (top-center) which prompts for the API name.  We should try to use something that is unique to your brand or company to avoid name collisions from other users. 

After the API management service is provisioned, the VS Code extension should display the recently created service. At this point, we can add a new API from a WSDL document. To do that and due to limitations on this extension, we need to open the API service from the Portal.  We can do this by doing a right click on the API service name and selecting “Open in Portal”.

Once the Azure Portal loads on the browser, we can click on the “Add API” menu option. This action loads a view which shows all the supported standards.

For our case, we should select WSDL. At this point, we need to have either a link or the actual WSDL file.  We also need to have the single WSDL file that contains all the web operations.  We can easily get that file by loading the SOAP API endpoint with the URL parameter singleWsdl as shown below:

https://api.ozkary.com/endpoint.svc?singleWsdl

 

Note: Replace the URL with the target endpoint

When we have either a link or the actual file, we can import it into the Azure API Management console.  For the import process, select the “SOAP to REST” option. This option enables us to convert the XML metadata into a REST metadata which is used to build the Web operations with JSON.  We should also use the API URL suffix to separate different areas of the APIs. This appends the suffix to the endpoint-based URL.

 

Recursive Error

Error: Parsing error : Unable to import API from WSDL: Element named 'http://schemas.ozkary.com/sample.xsd:Product' has a recursive definition. Recursive types are not supported.

If there is a recursive error, the import will not be able to complete the process. The error indicates that in one of the SOAP complex types, there is a property that has itself as type definition, and this causes the engine to do a recursive look up. This leads to infinite lookups which will never end thus causing the error.  The only way to fix this error is to change the complex type definition by removing the recursive type reference.

To illustrate this problem, let us look at an example. In the following Product complex type, we can see that there is a Product property which uses the same type (Product). This causes a recursive error as it endlessly looks at the type definition.

<xs:complexType name="Product">     <xs:sequence>         <xs:element minOccurs="0" maxOccurs="1" name="Name" type="xs:string"/>         <xs:element minOccurs="0" maxOccurs="1" name="SKU" type="xs:string"/>         <xs:element minOccurs="0" maxOccurs="1" name="Product" type="tns:Product"/>             </xs:sequence> </xs:complexType>

 

Testing the API

Once the WSDL is processed successfully, we can now look at the operations from the portal and even test them using the REST format.  This would be like how we can test using Postman or Swagger UI.  Note that there are two ways of testing the API. We can either use the Azure Portal or go back to VS Code and test the operations from the IDE. Independently of the selected method, the goal is to validate that the REST endpoint work.

Exporting to OpenAPI

Exporting the API metadata is very convenient for the purpose of generating documentation and client code for multiple languages like CSharp, JavaScript etc.

To export the API with all its operations using REST, we can click the ellipses (…) next to the API title and click “Export API”. At this point, we want to select of the OpenAPI standard. Most tools support both JSON and YAML formats

The export enables us to download all the operations in the format needed to properly document the APIs using tools like Swagger UI which shows all the API definitions and JSON payloads.

Conclusion

By using VS Code and Azure API Management service, we can quickly transform a legacy SOAP API into the modern OpenAPI standard without the need to re-code the API. Keep in mind however, that the SOAP API continues to be a system dependency under the hood. Nevertheless, we have taken an approach that can quickly help us provide a REST endpoint and use modern test and documentation tools to continue to support our SOAP APIs.

Thanks for reading.

Originally published by ozkary.com