SOAP Challenges

One of the main reasons that SOAP services are much less widespread than they might otherwise be is that it can be hard to create portable and easy to use SOAP services. Many SOAP services end up being less usable, complete, or portable than expected, which makes it hard to justify their extra setup cost. Several factors contribute to this:

• XML structures are richer than standard primitive structures. Consider the XML Query structure that is supported by Watson Explorer Engine. Each operator can contain either other operators or terms (as shown by the use of xs:choice in the schema). While this is a very natural XML structure and is a standard structure for Boolean queries, it does not neatly conform to primitive structures in most languages.
• Mapping between schema and primitive structures is inconsistent. This is a consequence of the previous point, because there is no single, complete standard for mapping XML structures to native structures. Toolkits have to make dozens of ad hoc decisions on how to do the translation (class names, attributes vs. elements, name collisions, xs:choice etc). This is so complex that there is no one Web Services toolkit that is able to handle any valid schema, let alone one that produces easy-to-use code.
• SOAP services only go so far in the exposition of their objects. An easy shortcut to developing SOAP services is to not fully describe XML objects, which makes the associated schema simpler but also under-specified, and therefore largely defeats the purpose of using SOAP vs. REST. For example, Microsoft Sharepoint (whose Web Services are used by the Watson Explorer Engine connector to that service) returns half of the information in escaped XML, wrapped into a SOAP message.

Because of these challenges, SOAP services are often designed to only be consumed by the tools that produced them. Providing and supporting a set of portable, usable, and full-featured Watson Explorer Engine SOAP services requires some assumptions and compromises:

• Focus on Visual Studio C# and Java 1.6+: Testing for the Watson Explorer Engine API focuses on Visual Studio C# and Java 1.6+, which are the most commonly languages used by Watson Explorer Engine customers to date.
• Use wrapper objects: The Watson Explorer Engine API uses a number of nested objects even though languages such as Visual Studio C# can collapse arrays to avoid extra container objects. Unfortunately, C# does not always correctly handle unbounded arrays. To address issues such as this while making our schema as portable as possible, the Watson Explorer Engine API preserves wrappers even if that may make the code a little more verbose.
• Simplify/modify objects to improve usability: In many cases, the order of sub-elements can be arbitrary (i.e., corresponding to xs:choice in the schema instead of xs:sequence), this flexibility can require cumbersome structures in C# and Java. The Watson Explorer Engine API imposes a specific ordering of sub-elements whenever that does not have any substantial impact on functionality.