Nav

APIkit for SOAP Tutorial

APIkit for SOAP helps you implement a SOAP interface for accessing data resources and integrating the interface with backend processes to function as an API. Using APIkit for SOAP you can transition the implementation to REST.

In this tutorial, you create an API using Studio and APIkit for SOAP. You can download the XML code for the API or follow the steps in this document to create the flows and corresponding XML in Studio.

Prerequisites

APIkit for SOAP supports consuming a remote WSDL. This tutorial, however, uses a local WSDL.

Create a New Project

You create a new project, specify the use of APIkit components, and refer to a WSDL file that you download.

To create an APIkit for SOAP project:

  1. Check that you are using a version of Studio that includes the Anypoint APIkit SOAP Extension: Help > Installation Details. If not, install Studio 6.0 or later.

  2. Download the example tshirt2.wsdl file to your local drive.

  3. Under the File menu, select New > Mule Project.

    The New Mule Project wizard appears.

  4. In Project Name, enter a name for the project. Select or accept the default EE runtime, for example Mule Server 3.8.1 EE.

  5. Check the Add APIkit components checkbox, and browse to the tshirt2.wsdl file you downloaded.

  6. Select a service and port from the drop-down menus. For example, select TshirtService and TshirtServicePort.

    apikit-for-soap-47fb8
  7. Click Finish.

    The new project having a src/main/wsdl folder that contains the WSDL file appears.

  8. Right-click a blank area of the canvas and run the project.

  9. Go to http://localhost:8081/TshirtService/TshirtServicePort?wsdl.

    The contents of the TShirtService WSDL file appear.

Implementing an Operation

By default, each flow you generate in Studio has a payload that identifies the current operation that needs to be implemented by returning a SOAP fault.

In this part of the tutorial, you use the SoapUI tool to identify an operation that you need to implement by requesting the API that fails. Use the OrderTshirt operation to create a request in SOAP UI to place an order for a large t-shirt for John. The API cannot handle this operation and a SOAP fault occurs.

To resolve the fault, you modify the API. You add the Transform Message component to the flow and specify a message in DataWeave transformation language for responding to the request, effectively implementing the operation. In the DataWeave code, you use the proper namespace to avoid a soap:Server faultcode at the beginning of the response to the request.

The Transform Message component works on the process side after the endpoint defined in the WSDL has been hit, triggering the main flow of the Mule application to execute, which then calls the backend flow.

To generate a SOAP fault:

  1. Create a SoapUI project using the http://localhost:8081/TshirtService/TshirtServicePort?wsdl for the initial WSDL:

    soapui-new-project.png

  2. In the SoapUI client, request a large t-shirt for John by entering some values into the request envelope. For example:

    • Enter L between the <size> tags.

    • Enter John between the <name> tags.

  3. Submit the request.

    The result is the SOAP fault.

    
                
             
    1
    2
    3
    4
    5
    6
    7
    8
    
    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
       <soap:Body>
          <soap:Fault xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
             <faultcode>soap:Server</faultcode>
             <faultstring>Operation [OrderTshirt:/TshirtService/TshirtServicePort/api-config] not implemented</faultstring>
          </soap:Fault>
       </soap:Body>
    </soap:Envelope>

To implement an operation to prevent the SOAP fault:

  1. Remove the Set Payload element from the flow OrderTshirt:api-config.

  2. Drag a Transform Message component from the Mule palette to replace Set Payload.

    Leave the Source section of the APIkit backend flow empty.

    apikit-for-soap-e8679
  3. Select the Transform Message component.

    The user interface displays the input and output for the current operation, OrderTshirt as input, and OrderTshirtResponse as output.

  4. In the properties editor, specify the payload as follows:

    
                
             
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    
    %dw 1.0
    %output application/xml
    %namespace ns0 http://mulesoft.org/tshirt-service
    ---
    {
      ns0#OrderTshirtResponse: {
        orderId: "I got a request from "
        ++ payload.ns0#OrderTshirt.name
      }
    }
    apikit-for-soap-475c0
  5. Save and rerun the project.

  6. In the SoapUI client, repeat the request.

    The output changes to a valid response:


         
      
1
2
3
4
5
6
7
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns0:OrderTshirtResponse xmlns:ns0="http://mulesoft.org/tshirt-service">
         <orderId>I got a request from John</orderId>
      </ns0:OrderTshirtResponse>
   </soap:Body>
</soap:Envelope>

Working with Headers

In the SoapUI, the request window shows the soap Envelope header.

apikit-for-soap-53dc2

In this part of the tutorial, you modify the API to get header information from the request and add header information to the outbound response. Additional header information that complies with the WSDL document is called APIUsageInformation.

  1. In the SoapUI, modify the OrderTshirt request by entering a value for the API key. For example, enter 987654321 between the <apiKey> tags.

  2. In Studio, edit the DataWeave code to get the API key, which is an inbound property, from the header:

    
                
             
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    
    %dw 1.0
    %output application/xml
    %namespace ns0 http://mulesoft.org/tshirt-service
    ---
    {
      ns0#OrderTshirtResponse: {
        orderId: "I got a request from "
        ++ payload.ns0#OrderTshirt.name
        ++ ", using the following auth header "
        ++ inboundProperties['soap.AuthenticationHeader'].ns0#AuthenticationHeader.apiKey
      }
    }
  3. Save and rerun the project.

  4. In SoapUI, send a request, and check that the response changes to the following:

    
                
             
    1
    2
    3
    4
    5
    6
    7
    
    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
       <soap:Body>
          <ns0:OrderTshirtResponse xmlns:ns0="http://mulesoft.org/tshirt-service">
             <orderId>I got a request from John, using the following auth header 987654321</orderId>
          </ns0:OrderTshirtResponse>
       </soap:Body>
    </soap:Envelope>

To add a header to the outgoing message that complies with the WSDL document:

  1. In Studio, open the tshirt2.wsdl in src/main/wsdl and scroll to APIUsageInformation element, which is the element expected by the contract. Copy the name of the element to the clipboard.

  2. On the canvas, select Transform message in the OrderTshirt:/TshirtService/TshirtServicePort/api-config flow, and in the properties editor, click Add new target:

    apikit-for-soap-3005f

    The Selection dialog for selecting a target appears.

  3. Select Property instead of Variable from the drop-down.

  4. In Variable name, paste the contents of the clipboard, and add soap. as a prefix. or type soap.APIUsageInformation.

    The complete variable name looks like this:

    soap.APIUsageInformation

  5. Click OK.

  6. Double-click the apiCallsRemaining: Integer.

    apikit-for-soap-41732

    Double-clicking apiCallsRemaining: Integer adds APIUsageInformation: { apiCallsRemaining: null } to the DataWeave code for the outbound property:

    
                
             
    1
    2
    3
    4
    5
    6
    7
    8
    9
    
    %dw 1.0
    %output application/xml
    %namespace ns0 http://mulesoft.org/tshirt-service
    ---
    {
      ns0#APIUsageInformation: {
        apiCallsRemaining: null
      }
    }
  7. Change null to 10.

  8. Save and rerun the project.

  9. In the SoapUI, execute the OrderTshirt request again. The response envelope from APIkit for SOAP is:

    
                
             
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    
    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
       <soap:Header>
          <ns0:APIUsageInformation xmlns:ns0="http://mulesoft.org/tshirt-service">
             <apiCallsRemaining>10</apiCallsRemaining>
          </ns0:APIUsageInformation>
       </soap:Header>
       <soap:Body>
          <ns0:OrderTshirtResponse xmlns:ns0="http://mulesoft.org/tshirt-service">
             <orderId>I got a request from John, using the following auth header 987654321</orderId>
          </ns0:OrderTshirtResponse>
       </soap:Body>
    </soap:Envelope>

Using Typed Faults

APIkit for SOAP supports typed SOAP Faults. The SOAP Fault processor has generic faults and the following types:

  • Soap Fault 1.1

  • Soap Fault 1.2

You can select either type using any WSDL file, even for those files that do not contain typed faults.

For the tshirt2.wsdl file, there is just one typed fault named TshirtFault, which is mapped to every operation that the WSDL has: OrderTshirt, ListInventory, and TrackOrder.

To make the ListInventory operation display the typed fault:

  1. In Studio, delete the Set Payload processor of the ListInventory:api-config flow.

  2. Search for fault in the palette, drag and drop SOAP Fault into the ListInventory:api-config flow.

  3. In the properties editor, select ListInventory from the Operation drop-down.

  4. Select or accept the default TshirtFault from the Fault Type drop-down.

  5. Add a Transform Message component before the SOAP Fault component.

  6. In the component properties, set up the following DataWeave code:

    
                
             
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    
    %dw 1.0
     %output application/xml
     %namespace ns0 http://mulesoft.org/tshirt-service
     %namespace soap http://www.w3.org/2003/05/soap-envelope
    ---
     soap#Fault: {
       faultcode: "soap:Server",
       faultstring: "The error details",
       detail: {
         ns0#TshirtFault: {
          errorStuff: 500
         }
       }
     }
  7. Save and rerun the project.

    Using the SoapUI client, run the ListInventory operation.

    The client returns the following envelope instead of the default fault:

    
                
             
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    
    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
       <soap:Body>
          <soap:Fault xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
             <faultcode>soap:Server</faultcode>
             <faultstring>The error details</faultstring>
             <detail>
                <ns0:TshirtFault xmlns:ns0="http://mulesoft.org/tshirt-service">
                   <errorStuff>500</errorStuff>
                </ns0:TshirtFault>
             </detail>
          </soap:Fault>
       </soap:Body>
    </soap:Envelope>

Updating a WSDL File

After modifying a WSDL, such as adding an operation or editing a message, regenerate SOAP flows. Because modifying a WSDL is error-prone, before making a change, make a backup, change the attribute, and verify that the change worked.

To update a WSDL file:

  1. Download tshirt-modified.wsdl, copy the entire contents of the downloaded file, and paste it in tshirt2.wsdl, replacing the tshirt2.wsdl content.

  2. In Package Explorer, right-click the project and select Mule > Generate SOAP Flows.

    A new flow named DeleteOrder:api-config appears.

    generate-sources.png

See Also