Send Docs Feedback

Tutorial: Proxy a SOAP service

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.

RESTful API or SOAP Pass-through?

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

In contrast, with a pass-through proxy, clients simply pass in a SOAP payload. This is a way to have SOAP service calls benefit from Edge management features.

  1. Go to the Edge management UI for the organization you'll be working in. For Edge cloud, go to https://enterprise.apigee.com, log in, and select the organization you want to work in.
  2. On the main menu, click APIs > API Proxies, then click the + API Proxy button.
  3. In the Build a Proxy wizard, select SOAP service.
  4. Click Next.
  5. In the Details page, fill out these fields:

    In this field do this
    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. In 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. In the Security page, select Pass through (none).
  10. Click Next.
  11. Accept the Virtual Host defaults, and click Next.
  12. In 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.

If you'd chosen the pass-through SOAP type, Edge would have displayed a list of operations with the SOAP payloads that clients would be expected to pass.

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"

The LicenseKey query parameter value is a dummy/test value for the service.

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.

 

Help or comments?