Proxy a SOAP service

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

What you'll learn

Through this tutorial, you'll learn to:

  • Generate an Edge API proxy from a WSDL file.
  • Know the difference between a RESTful SOAP proxy type and a pass-through SOAP proxy.

In this tutorial, you'll learn how to put an Edge API proxy in front of a SOAP-based web service.

This tutorial illustrates how to generate a new RESTful API in front of your SOAP-based service. Though it's not described in detail here, you can also generate a pass-through proxy that accepts a SOAP payload and passes it to the backend service.

What you'll need

Creating the proxy

Here, you'll have Edge generate the proxy that will sit in front of a SOAP service. There are two types of SOAP API proxies:

  • REST-SOAP-REST proxy type generates a new RESTful API with a translation layer to SOAP. Clients call it as they would other RESTful services, passing the query parameters needed by the backend service. Edge translates this into the SOAP payload expected by the service.
  • Pass-through proxy proxy type enables clients to simply pass in a SOAP payload. This is a way to have SOAP service calls benefit from Edge management features.

Edge

To proxy a SOAP service using the Edge UI:

  1. Sign in to apigee.com/edge.
  2. Select Develop > API Proxies in the left navigation bar.
  3. Click +Proxy.
  4. Click SOAP service.
  5. On the Proxy details page, enter the following:

    Field Descriptoin
    WSDL source

    Select: URL

    Copy and paste the following WSLD URL in the Enter URL field:

    https://ws.cdyne.com/delayedstockquote/delayedstockquote.asmx?wsdl

    Click: Validate

    Apigee Edge gets the WSDL file and reads it to discover the list of operations the SOAP service supports.
    Name

    Leave as is: delayedstockquote

    This is name for the API proxy you're creating.
    Base path Leave as is: /delayedstockquote
    Description Optionally add a description, such as: Stock quote WSDL API Proxy
  6. Click Next.
  7. On the Common policies page, under Security: Authorization, select Pass through (no authorization).
  8. Click Next.
  9. On the WSDL operations page, select: REST to SOAP to REST.

    Once you select the proxy type, Edge displays the list of operations for which it will generate REST API paths. This list enables you to select from among the operations found in the WSDL (in case you have a particular set you're looking for). Notice that the table also displays resources that a REST client can use to call the backend SOAP service.

    Leave all other selections on the page as is.

  10. Click Next.
  11. Accept the Virtual Host defaults by clicking Next.
  12. On the Summary page, under Optional Deployment click Test and click Create and deploy.

    Edge generates a RESTful API proxy and deploys it to the test environment. From the WSDL, it determines the service's supported operations, input parameters, and so on. Edge suggests 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.

    Unless you're customizing the new API proxy (and you aren't in this tutorial), that's all there is to it. You can move on to testing the new API proxy.

Classic Edge (Private Cloud)

To proxy a SOAP service using the Classic Edge UI:

  1. Sign in to http://ms-ip:9000, where ms-ip is the IP address or DNS name of the Management Server node.
  2. Select APIs > API Proxies in the top navigation bar.
  3. Click + API Proxy.
  4. Click SOAP service.
  5. On the Proxy details page, enter the following:

    Field Descriptoin
    WSDL

    Select: Example URL

    Then select:
    ...delayedstockquote.asmx?WSDL

    Click: Validate

    Apigee Edge gets the WSDL file and reads it to discover the list of operations the SOAP service supports.
    Proxy Name

    Enter: delayedstockquote

    This is name for the proxy you're creating.
    Proxy Base Path and Description Leave as is.
  6. Click Next.
  7. On the WSDL page, make these selections:
    In this field do this
    API Proxy Type

    Select: REST to SOAP to REST

    Once you select the proxy type, Edge displays the list of operations for which it will generate REST API paths, as shown here. This list gives you a chance to select from among the operations found in the WSDL (in case you have a particular set you're looking for). Notice that the table also displays resources that a REST client can use to call the backend SOAP service.

    For now, just leave the first set of operations selected.
    Port Type: DelayedStockQuoteSoap Select all three WSDL operations. Leave other settings as is.

  8. Click Next.
  9. On the Security page, select Pass through (none).
  10. Click Next.
  11. Accept the Virtual Host defaults, and click Next.
  12. On the Build page, accept the defaults and click Build and Deploy to have Edge start generating the proxy.

    Edge generates a RESTful API proxy. From the WSDL, it determines the service's supported operations, input parameters, and so on. Edge suggests 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.

    Unless you're customizing the new proxy (and you aren't in this tutorial), that's all there is to it. You can move on to testing the new proxy.

Testing the proxy

To try out the proxy you've created, open a command prompt and use cURL. Type the command below, where:

  • ORG is the name of the Edge organization in which you created the proxy.
  • ENV is the environment the proxy is deployed to.
  • DOMAIN corresponds to the Edge instance you're using.
curl "https://{ORG}-{ENV}.{DOMAIN}/delayedstockquote/quote?StockSymbol=GOOG&LicenseKey=0"

For example, if your organization is docfood, environment is test, and you're using the Edge enterprise cloud, you'd run a command like this:

curl "https://docfood-test.apigee.net/delayedstockquote/quote?StockSymbol=GOOG&LicenseKey=0"

If you entered GOOG for the StockSymbol query parameter, you should get the current price for Alphabet Inc. Class C stock. For example:

{  
   "GetQuoteResponse":{  
      "GetQuoteResult":{  
         "StockSymbol":"GOOG",
         "LastTradeAmount":819.55,
         "LastTradeDateTime":"2017-02-13T14:33:00",
         "StockChange":5.88,
         "OpenAmount":816.0,
         "DayHigh":820.96,
         "DayLow":815.49,
         "StockVolume":785064,
         "PrevCls":813.67,
         "ChangePercent":"+0.72%",
         "FiftyTwoWeekRange":"663.28 - 841.95",
         "EarnPerShare":27.88,
         "PE":29.4,
         "CompanyName":"Alphabet Inc.",
         "QuoteError":false
      }
   }
}

Get the auto-generated OpenAPI Specification

When you proxy a SOAP service using "REST to SOAP to REST," Edge automatically generates an OpenAPI Specification. You can use the OpenAPI Spec to generate API documentation for the API.

To get the OpenAPI Spec, simply visit this URL:

curl https://{ORG}-{ENV}.{DOMAIN}/delayedstockquote/openapi.json

Extra credit: How do you find out which resource, verb, and query parameters to use?

In the test API call, you used a specific resource and query parameters in your cURL call to the backend SOAP service. But how would you find that out on your own?

Resource and verb

In the API proxy wizard when you were creating the proxy, you saw how the SOAP operations would map to API verbs and resources. But if you didn't write those down, here's how you'd find out after the proxy is created.

On the API proxy's Develop tab, in the left Navigator pane you'll see a list of flows under the Proxy Endpoints. Click the flow you're interested in. For example, the GetQuote flow is a good candidate. Then view the XML in the Code pane, which shows the resource path and verb for the flow in the <Condition> element: /quote and GET.

Query parameters

With the GetQuote flow selected, click the first policy in the graphical flow view. It should be an Extract Variables policy that captures query parameters that are expected to be passed: StockSymbol and LicenseKey. (If you do a web search for the SOAP service, it tells you what to pass for the LicenseKey.)

The captured query parameters are saved as variables and used by the next policy to construct the SOAP message.