What are some best practices for connecting Apigee Edge to SOAP endpoints?

[#1]

Are the specific concerns that come with connecting to SOAP targets? An example or two of things to do, not do, or at least be aware of would be helpful. Thanks!

[gnanasekaran]

ok, let me share my experience with this

If you want to create just a SOAP Passthro Proxy

-> DO NOT use the soap wizard and try to load wsdl - you don't need it, just configure a regular reverse proxy [pass through] - use the service location in wsdl as the Target Endpoint

-> you would need to handle [?wsdl] to replace the service location in the response to apigee's proxy endpoint

-> With SOAP service, you just have one resource URL, so default analytics is kind of limiting without flows - So i usually add 'SOAPAction' header as a custom dimension, so you get method/operation level analytics

-> It's always a good practice to add Traffic Mangement policies [SpikeArrest, Ratelimit, MessageValidation, ThreatProtection at the API layer]

If you are planning to expose your SOAP service as a RESTful API

> DO use the wizard to fetch wsdl and generate operations - you may not use this directly 'as-is' - but it generates all the soap boilerplate code that will be very very helpful when you start designing your REST APIs

> Review the generated REST URI Paths, parameters - you have control over resource names, paths and parameter names - change it so it matches with your design

> Credential Mediation - typically you expose OAuth on the REST, while your SOAP might do bunch of WS* stuff. OAuth -> WS* mediation is much easier if you use standard webservices libs like jax-ws and wrap the functionality in the Javacallout, it takes care of generating necessary soap headers for you

> in this case, you don't have to worry about wsdl handling or custom analytics - that is a derived benefit of doing REST

[kurtkanaskie]

Here is my experience.

Some backends (e.g. SAP) provide a micro-services or singular style WSDL, that is one WSDL with one operation. Therefore the proxy will need to use multiple WSDLs to create a proxy with the right context. I call this proxy design pattern "proxy-to-multiple-wsdls".

To create this proxy you can start with the WSDL wizard to see what Apigee does with a WSDL and follow that pattern for the additional WSDLs. I solved this situation before the wizard was available but the pattern is generally the same.

Create a RESTful resource endpoint using verb and collection/entity that corresponds to a specific backend WSDL endpoint (e.g. GET orders, GET orders/{id})

Then the high level flow for each API resource endpoint is:

REQUEST:

* Extract Variables to get RESTful request parameters (URL params, query params) and body (PUT, POST).

* Assign Message to create the SOAP request, change verb, add authorization and set target URL variable for the specific WSDL endpoint.

* Javascript callout to set the target URL from variable.

RESPONSE:

if backend response is not OK (2xx)

* Extract Variables to get the SOAP fault message.

* Raise Fault with the SOAP fault message.

else

* XSL Transform the backend response to the RESTful response.

* XML to JSON conditionally based on request parameters (e.g. request.header.accept != "application/xml")

In this proxy you will have to manage groups of policies (Extract Variables, Assign Message, XSL Transform) for each resource, so pay attention to naming conventions. I use the policy naming and display naming convention of {noun}-{verb}-{policy} (e.g. Orders-Get-AExtractVariables, Orders-Get-AssignMessage, Orders-Get-XSLTransform) so the policies are grouped and sorted by flow sequence, in the policy navigation pane which sorts by Display Name.

Once I clean up my sample proxy, I'll share on Github.

[#4]

To reiterate a point from @Mukundha Madhavan - the SOAP wizard provides you a great starting point, but is not an end unto itself. If your goal is to expose a RESTful service, then you surely will need to modify URLs, payloads, and request/response semantics.

[gargi_talukdar]

In Request side we can use Assign Message policy to create the SOAP request,change verb, add authorization and set target URL variable for the specific WSDL endpoint. While change verb, add authorization needs to be done using Assign Message policy, but according to my experience I feel creation of SOAP payload should be done using XSL Transform policy as many a times in SOAP payload we have come across situation where in we have to create an element only when particular condition satisfies (create the tag only when values is present, as sending null tag breaks the backend).

To handle such scenarios, I guess XSLT is the best solution as we cannot have condition inside Assign Message policy.

[kurtkanaskie]

Yes, XSLT would certainly work here and would also be useful when the POST message is complex. Alternatively, you could use a JavaScript callout to conditionally set the body.