SOAP API Expects String Element?

Question

Lately I've been interacting with a handful of SOAP APIs from different enterprise systems and I'm somewhat puzzled that oftentimes the WSDLs seem to indicate that they should be receiving XML data as a "string". For example a WSDL indicate the service expects data conforming to the following snippet of XSD for some operation:

...
<s:element name="PostSomeData">
  <s:complexType>
    <s:sequence>
      <s:element minOccurs="0" maxOccurs="1" name="Data" type="s:string"/>
    </s:sequence>
  </s:complexType>
</s:element>
...
<wsdl:message name="PostNewhireRecordSoapIn">
  <wsdl:part name="parameters" element="tns:PostSomeData"/>
</wsdl:message>
...

When in fact the contents of the Data tag itself must contain some XML, usually escaped or as Character Data(<![CDATA[<SomeStructuredData>...</SomeStructuredData>]]>) that adheres to some schema that may or may not be provided.

What gives? Why is there a proclivity for APIs to be designed such that SOAP webservices expect xsd:string? It seems like. if I'm going to use SOAP, I should be describing the structure of the XML expected rather than just define the webservice as expecting a string of XML.

Answer 1

Normally this isn't good design. There is not much of a contract is all the service is: "insert giant string here".

The WSDL should define a contract which is explicit between the callee and caller. If all the contract is an undefined string format, it will be difficult and cumbersome to work with.

However, sometimes this is necessary if the service is a pass through or is storing the contents of secondary service call within the payload.

I don't know the context of your situation but there may be good reason for this implementation.

Usually, this is a misguided attempt to extend the service without changing the schema because the string can be anything so the official WSDL contract never changes.

Answer 2

I may be slightly wrong on the historical details, but I believe that originally, SOAP was designed to operate as an RPC (Remote Procedure Call) system. You would define a service like you would a function in a procedural programming language, with argument and return types, e.g. function foo(string arg1, int arg2) returns string.

Only a handful of primitive types were defined by the core standards, but more complex ones were expected to be declared as part of the service definition using WSDL, XSD, etc. From an RPC perspective, the input and output was never XML, it was a set of data structures which had been transported over XML.

In practice, though, complex data structures are very hard to make portable, so it turned out to be easier to treat the XML document itself as the input and output, and let processors on each end decide how to process that document. This leads to the "document/literal" style of using SOAP, where the input and output are defined as full XML documents, not a set of input and output parameters.

However, a lot of enterprise SOAP integration tools are still built around the RPC concept, and so don't lend themselves to the "document/literal" way of working; they might require a complex service definition to understand the "real" types being "serialized" in the XML document. As a workaround, people build a SOAP RPC service which expects and returns single strings, and then transport complete XML documents as opaque strings.

This allows the developer to reuse the SOAP component of their framework to handle the transport and some basic error handling, then define their real service as XML in, XML out.

At best, such a service can use the SOAP envelope as a standardised wrapper for authentication, session management, etc; at worst, it simply adds a bunch of overhead on top of HTTP which wouldn't be necessary if SOAP had never existed.