Import WSDL

This feature enables SOAP services described in WSDL documents to be partially converted to REST APIs. You can then use the registered API to call SOAP services and operations more directly and using REST architecture formats.

When the API Manager reads the imported WSDL file, all Ports and Operations present in the file are transformed into Resources and Operations of a REST API.

Architecture

Internally, the execution flow of a requisition to a WSDL service occurs as follows:

We will consider for the examples below the use of an API with a WSDL operation named /convertweight http://www.webservicex.net/ConvertWeight.asmx?WSDL.
wsdl call arch

The image above represents what happens in the Gateway during a call. First, the data on the body of the request are transformed from JSON to XML. Then, the XSL Transformation interceptor performs the transformation by mapping the XML data in the body with the XSL present inside the interceptor itself for the creation of a SOAP envelope valid to be used later in a common HTTP POST request, as shown in the image below.

wsdl call back

After the SOAP server returns the execution response of the POST call, this response returns to the Gateway to go through another transformation. The SOAP envelope with the outcome of the operation goes through an XSL Transformation interceptor again, which has the role of transforming the contents of the SOAP envelope into a JSON by using the mapping present in an XSL document saved within the interceptor. When this transformation is concluded, the gateway returns a JSON body to the client.

Importing a WSDL

Registering an API for WSDL use is similar to registering a common API. Click the Import WSDL button in the Resources section of the API (either when you are creating a new API or editing an existing one).

wsdl import button

Clicking the button will open a modal window, where you can import the WSDL file in two ways: insertion the URL where the WSDL is hosted,

wsdl import url modal

or uploading a .wsdl or .xml file:

wsdl import file modal

After choosing the method for adding the WSDL file, click the Validate button. The content of the file will only be uploaded into the server if the data and the URL are correct.

The Validate button will return error messages in case the uploaded file or the URL is invalid. In case of failure when reading the WSDL of a URL, the following message will be displayed:

wsdl invalid url

In this case, the URL is correct, but the WSDL could not be read because its content was somehow invalid.

In turn, if the URL format is invalid (only URLs starting with http(s):// are accepted), the following message will be displayed:

wsdl invalid url format

If the format isn’t accepted, the Validate button won’t be enabled.

If the URL is correct and the content of the WSDL file is valid, the Upload button will be enabled and the file can be submitted to the server.

wsdl valid url content

If the WSDL is imported directly in a file, not a URL, the validation is presented as follows: if you try to validate a file with an invalid extension, the message "Invalid WSDL Format" will show up, indicating that the format of the file is not accepted. Only .wsdl and .xml are valid extensions.

wsdl invalid file format

If the format of the file is valid but its content has problems, the validation error message will be this:

wsdl invalid file load

In the image above, the message happens because the content of the WSDL is invalid, causing a loading error.

If the file has valid content and extension, the Validate button returns a successful message and the Upload button is enabled.

wsdl valid file upload

After the upload, the user will be directed to the list of services and operations present in the WSDL. In the example shown below, we are using the WSDL of the tracking service of the Brazilian Post company, available on their website: https://github.com/wmixvideo/correios/blob/master/src/main/java/br/com/correios/webservice/rastro/Rastro.wsdl.

wsdl listing

The screen shows each service described in the WSDL (in this case, ServicePortBinding) with its set of operations (buscaEventosLista and buscaEventos).

When a WSDL service row is expanded, you can see the following information:

  • WSDL Operation: it represents the operation present within the WSDL and available in the exposed SOAP service.

  • Description: non-mandatory information on what that operation does.

  • REST Method: used to create the REST resource, it represents the method from by which the API resource will be registered. By default, this method is always POST, because it is accepted by SOAP services. For other cases, it may be necessary to create transformations via interceptors for method conversion.

  • REST Operation: it represents the REST operation that the element will become.

To turn each of these operations into features of your API, select the desired items, define the HTTP method that each one will represent, and change the name of each resource, if necessary.

After you do this, click the Save and return to Resources button. You will be redirected to the list of resources with the items already transformed:

wsdl selecting operations

After this step, you can go on with the normal API creation flow.

If you need to add or edit a resource created from a WSDL, you must import the file again, and all resources already registered that are part of that WSDL will be marked in the operations display.

The destination URL of your new REST API resources will be the endpoint of the WSDL service.

After importing a WSDL file and creating the related resources, six interceptors will be included to aid the call and execution of each operation generated from the WSDL. Access the Interceptor’s documentation for more information. They are:

Request Flow

1 XSL Transformation

This interceptor contains a XSL file for transformations in the gateway.

2 Header interceptors

The first header interceptor indicates the Content-Type used for inbound information traffic (text/xml). The second interceptor indicates the value of the SOAPAction in the operation to be performed. If the service does not have a SOAPAction assigned, this interceptor will not be created.

1 HTTP Method

Made for the conversion of the method to POST, following the SOAP standard.

Response Flow

1 XSL Transformation

It contains the XSL file responsible for transforming the call response to the JSON format, following the mapping in the file.

1 Header

This interceptor indicates the Content-Type used in the server response (application/json).

wsdl interceptors

The image above shows the application of interceptors in the resource /buscaeventos. These interceptors will be used by the Gateway for the execution of calls to this or other operations created.

If necessary, all present interceptors can be edited, and new interceptors can be added to assist in the execution of the processes.
Thanks for your feedback!
EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]