This topic explains how to create API proxies for SOAP-based web services. You can create two kinds of SOAP proxies in Edge. One generates a RESTful interface to the backend SOAP service and the other performs a "pass through" of the SOAP message to the backend. Both techniques are described in this topic.

Creating a RESTful API proxy to a SOAP-based service

This section explains how to create a RESTful SOAP API proxy with the REST to SOAP to REST option in the Create New Proxy dialog.

Overview

The REST to SOAP to REST option processes the WSDL to generate a RESTful API proxy. Edge determines from the WSDL the service's supported operations, input parameters, and so on. Edge "guesses" which HTTP method to use for each operation. Typically, Edge translates operations into GET requests, which have the advantage of being cacheable. Edge also sets up the backend target endpoint, which can vary per SOAP operation. 

Basic steps

  1. From the Dashboard, click + API Proxy
  2. In the New Proxy API dialog, select WSDL as the starting point. 
  3. Select the source of the WSDL.
    • URL - Enter the URL of the WSDL you wish to use. 
    • File - Choose a WSDL file on your file system. In cases where there are additional dependent files, you can select all of them. 
    • Example URL - Select from a list of WSDLs for publicly available web services. These are handy for trying out the SOAP/API proxy features of Edge.
  4. Click Fetch WSDL.
  5. Select the API proxy type REST to SOAP to REST.

    Note: A table appears listing the operations that Edge "discovered" in the WSDL file. You can select and configure which operations you wish to incorporate into your API proxy. The table is shown in the following figure. 

    Operations on the callback porttype cannot be converted to REST resources because API Services does not support asynchronous operations for this purpose.


     
  6. Select from the Port Type column which set of operations you wish to use. In WSDL, port type elements define the operations that you can call on a web service. 
  7. Optionally change the HTTP Method associated with the operation.

    Note: Edge makes a "best guess" in determining the HTTP method to use for each operation. GET is generally preferred because GET requests can be cached.
     
  8. Optionally change the REST API path for an operation. The path will be used as the resource name in the API proxy URL.

    Note: Any parameters for an operation are listed in the REST API Parameters column. For example, the weather API shown in the previous figure includes a ZIP parameter for certain operations. In the API proxy, you specify that value as a query parameter.
     
  9. Complete the rest of the dialog and click Build. Edge generates and deploys the new API proxy based on the WSDL.
  10. Go to the summary page for the new API proxy. Note that a set of resources have been constructed based on the operations discovered in the WSDL file, as shown in the following figure.

    On the proxy's Overview page, the Resources list provides a detailed description of the new API, its operations, and parameters. You can think of this representation as the API's reference documentation. Edge generates this view of the API model automatically for you. Simply expand a resource to see its description and information about its input parameters, data types. Also listed are any enumeration facets that apply to an input parameter. Enumeration facets specify the list of the acceptable values for an input parameter.

About the final proxy

When Edge generates an API proxy based on a WSDL, the resulting proxy is actually a complex flow that includes policies for transforming data, extracting and setting variables, manipulating messages, adding threat protection, and more. After you generate a proxy based on a WSDL, take a look at the resulting flow in the Develop view of the API management UI. There, you can see exactly which policies have been added.

For example, the following figure shows the Target Endpoint Preflow part of a SOAP-based proxy. On the request side, an AssignMessage policy is used to set the target URL. On the response side, policies execute to transform the response from XML to JSON, extract the SOAP body part of the response into a variable, and set the response message. These policies (and others) are added automatically when you create the proxy.

Creating a pass-through proxy to a SOAP-based service

This section explains how to create a pass-through proxy with the Pass-Through Proxy option in the Create New Proxy dialog.

Overview

The Pass-Through Proxy option lets you to create a proxy that passes the SOAP message in a request to the backend service "untouched", making it very easy to create a proxy for a SOAP-based web service. Behind the scenes, Edge handles any transformations and other flow activities for you automatically. For example, if the request happens to be in JSON format, Edge takes steps to convert it to a valid XML SOAP message with correct namespaces before POSTing it to the service. Similarly, when the service returns an XML-based SOAP response, Edge translates it back to JSON before returning it to the client. In addition, Edge sets up the backend target endpoint, which can vary per SOAP operation. 

You might wish to choose Pass-Through if the WSDL operations support a lot of unbounded parameters. It's easier for Edge to translate a WSDL containing bounded parameters to a proxy, because they are finite and therefore can be represented by a finite set of query parameters or form variables.

Basic steps

  1. From the Dashboard, click + API Proxy
  2. In the New Proxy API dialog, select WSDL as the starting point. 
  3. Select the source of the WSDL.
    • URL - Enter the URL of the WSDL you wish to use. 
    • File - Choose a WSDL file on your file system. In cases where there are additional dependent files, you can select all of them. 
    • Example URL - Select from a list of WSDLs for publicly available web services. These are handy for trying out the SOAP/API proxy features of Edge.
  4. Click Fetch WSDL.
  5. Select the API proxy type Pass-Through Proxy. 

    Note: A table appears listing each WSDL operation and its corresponding SOAP payload. This is the payload that is "passed through" to the backend SOAP service. 

  6. Select from the Port Type column which set of operations you wish to use. In WSDL, port type elements define the operations that you can call on a web service. 
  7. Complete the rest of the dialog and click Build. Edge generates and deploys the new "pass-through" API proxy.
  8. Go to the summary page for the new API proxy. Note that a set of resources have been constructed based on the operations discovered in the WSDL file, as shown in the following figure.

In the proxy's Overview page, the Resources list provides a detailed description of the new "pass-through" API proxy. You can think of this representation as the API's reference documentation. Edge generates this view of the API model automatically for you. Simply expand a resource to see its description. The SOAP message body that is POSTed to the backend service is captured in the model view, as shown in this figure. Note that the method used for Pass-Through proxies is POST. This is the only method supported by the SOAP protocol. 

About the final proxy

When Edge generates a pass-through proxy, the resulting proxy is actually a complex flow that includes policies for transforming data, extracting and setting variables, manipulating messages, adding threat protection, and more. After you generate the pass-through proxy, take a look at the resulting flow in the Develop view of the API management UI. There, you can see exactly which policies have been added.

For example, the following figure shows the Target Endpoint Preflow part of a pass-through proxy. On the request side, an AssignMessage policy is used to set the target URL. On the response side, policies execute to transform the response from XML to JSON, extract the SOAP body part of the response into a variable, and set the response message. These policies (and others) are added automatically when you create the proxy.

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)