Send Docs Feedback

Exposing a SOAP service as an API proxy

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.

This video provides and end-to-end demo of turning a SOAP service into a REST service with Apigee Edge using the API proxy wizard. However, if you want more control over the SOAP-to-REST transformation, you can build a proxy using policies. For more information, see this Community post.

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 Build a Proxy wizard.

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 Build a Proxy wizard, select SOAP service.
  3. Click Next.
  4. In the Details page, make these selections. You must click Validate after selecting a WSDL.
    In this field do this
    WSDL

    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.
    Proxy Name

    This is name for the proxy you're creating.

    Proxy Base Path

    The Proxy Base Path is a URI fragment that uniquely identifies the API that is exposed by this API proxy. API Services uses the Base Path URI to match and route incoming request messages to the proper API proxy. (The Base Path is appended to the domain of the API, which is automatically generated based on your organization name and the environment where the API proxy is deployed.) It's a best practice to include a version number in the project name, for example, /v1/weather. This will determine how your API is invoked by consumer apps.

    Note: The Proxy Base Path defaults to the value specified for Proxy Name converted to all lower case unless you explicitly edit the content in the Proxy Base Path field.

    Description A brief description of the proxy.
  5. Click Next
  6. In the WSDL page, 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. 


 

  1. 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. 
  2. 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.
     
  3. 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.
     
  4. Click through the rest of the wizard to add security, select virtual hosts, and deployment environment.
  5. In the Build page, click Build and Deploy. Edge generates and deploys the new API proxy based on the WSDL.
  6. 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.

    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 path information.

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 Build a Proxy wizard, select SOAP service.
  3. Click Next.
  4. In the Details page, make these selections. You must click Validate after selecting a WSDL.
In this field do this
WSDL

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.
Proxy Name

This is name for the proxy you're creating.

Proxy Base Path The Proxy Base Path is a URI fragment that uniquely identifies the API that is exposed by this API proxy. API Services uses the Base Path URI to match and route incoming request messages to the proper API proxy. (The Base Path is appended to the domain of the API, which is automatically generated based on your organization name and the environment where the API proxy is deployed.) It's a best practice to include a version number in the project name, for example, /v1/weather. This will determine how your API is invoked by consumer apps.

Note: The Proxy Base Path defaults to the value specified for Proxy Name converted to all lower case unless you explicitly edit the content in the Proxy Base Path field.

Description A brief description of the proxy.

  1. Click Next.
  2. In the WSDL page, select the API proxy type Pass-Through SOAP.

    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. 


     
  3. 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. 
  4. Click through the rest of the wizard to add security, select virtual hosts, and deployment environment.
  5. In the Build page, click Build and Deploy. Edge generates and deploys the new API proxy based on the WSDL.

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. 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.

Advanced SOAP-to-REST proxy development

The previous sections covered the creation of a SOAP-to-REST API proxy using the API proxy wizard in Edge. However, if you want more fine-grained control over the SOAP-to-REST transformation, you can bypass the automation provided by the wizard and build a proxy by manually adding and configuring policies to get the behavior you want. For more information, see this Community post.

 

Help or comments?