SOAP Worst Practices Part 2: Trying to Be Too Flexible

(This is the second in a series of articles that attempt to expose some of the more common mistakes and misunderstandings people make when implementing a SOAP Web Service.)

XML is a quite flexible data format. It allows the user many options, such as Choices, Sequences, Complex Types, Type Extension. But the flexibility can very easily be overdone. While it may seem like a good idea to have your service be flexible, it also makes using the service that much harder to use because of all the different formats that need to be handled.

A good example of taking flexibility too far is the Web Services interface. It takes the idea of Type Extension to the absolute extreme. For those not familiar with Type Extension, see this tutorial. Type Extension can be very useful when you have types that are mostly similar, with just a few extra attributes added onto the extended types. For example, a good usage could be a personnel data model. Employees and Managers share most of their attributes like name, address, birthdate, department, etc. The only real difference is that Managers have other Employees that they manage. So we would have a base Complex Type of Employee, with an extended type called Manager which just adds a sequence of employees.

However, with the implementation, it goes much further. It has a base type named SObject which basically just has one attribute, the ID. All of their other types extend this base type, and add all of their attributes. A problem with this is that it causes a lot of redundancy. There are a lot of fields that are common to most types, for example Name, or Description, or CreatedDate. Those fields are defined over and over in every extension type that needs them. This not only bloats the document, but also adds extra complexity. Say you want to change one of those fields. You’ll have to edit it in all those places, greatly increasing the chances of error, as opposed to just editing it once in the base type.  This is just the “minor” problem, though.

The bigger problem happens because of this combined with two other issues:

1. They have over 150 extension types.

2. Everywhere one type references a list of another type, it uses the SObject type. Even if the items in that list will always be of the same type.

While this is flexible, it makes the consumer implementation a nightmare. As far as the WSDL says, everywhere that an SObject is referenced, it could be any of the 150+ types. Again, even if it will always be the same type, there is nothing in the WSDL that tells you that. So, if your application uses the WSDL as its instructions, as it should, then you need to account for all types in that location. This exponentially increases the work involved.

One quick improvement would be to reference the extension types where appropriate instead of the base generic type. For example, if an Account references a list of AccountPartners, make it a list of AccountPartners, not a list of SObjects. While both are technically valid and will accept the correct data, using the generic SObject type would mean that any subtype is “valid” data there, when it really is not. The consumer then has to account for all of those possibilities, even when in practice they will never happen.

When done correctly, flexibility can be a very useful thing. But as I’ve shown here, it can easily be taken too far, and cause more problems than it solves.

One thought on “SOAP Worst Practices Part 2: Trying to Be Too Flexible

  1. Pingback: SOAP Worst Practices Part 3: Not Completely Specifying the Message Format | EXTOL Business Integration Blog

Leave a Reply

Your email address will not be published. Required fields are marked *