Web Service Development - Best Practices

As a software developer I have had to deal with a fair amount of Web Services, both as the consumer and provider of services.  Below is a list of best practice guidelines that I have gradually assembled and try to follow when developing Web Services.  I also usually send this list to people that are writing Web Services that I am to consume.  I have found that it saves me considerable headache when it comes time to integrate with the service.  Most of my guidelines are written with XML over SOAP in mind, but some are common sense tips that should apply to other types of Web Services, like JSON over REST.

The Guidelines

1. A Web Service should be defined with a WSDL (or WADL in case of REST) and all responses returned by the Web Service should comply with the advertised WSDL.
1. This can for example be tested with tools like SoapUI (see my blog entry Web Service Testing with soapUI) or XMLSpy, which validate SOAP responses against a WSDL.
2. Use XML Schema to define the input and output of your Web Service operations.
1. Make sure to define return types for all returned data, preferably as XSD ComplexTypes.
2. Do not use the AnyType tag, as it makes it impossible (or non-beneficial) to use XML binding libraries to auto-generate code to construct request/response objects.
3. For ComplexTypes, make sure the occurrence indicators (minOccurs and maxOccurs) are correctly defined, so that it is clear to the consumer which fields are required and which are optional and the frequency of each field.
4. Make sure your namespaces are well defined (not some default like "org.tempuri")
3. Do not use a proprietary authentication protocol for your Web Service.  Rather use common standards like HttpAuth or Kerberos.  Or define username/password as part of your XML payload and expose your Web Service via SSL.
4. Keep it simple  
1. Write a Web Service with many simple methods rather than one large method (with numerous arguments) that tries to be everything to everyone.
2. Adhere to the OO principles of maximizing cohesion and minimizing coupling when designing your Web Services.
5. Make sure your Web Service returns error messages that are useful for debugging/tracking problems.  For example, include an error code and a human readable error description.
6. Make sure to offer a development environment for your service, which preferably runs the same Web Service version as production, but off of a test database rather than production data.
7. Thoroughly test your Web Service, in a technology-agnostic manner, before having others integrate with it.

Consequences of Breaking These Guidelines

Why all these rules?  Because I have found it to significantly increase development time for the consumer when they are broken.  Here are some of the offenders I frequently come across, and the resulting consequences:

• Web Services that don't define a WSDL and are poorly documented.
• This usually leaves the consumer shooting in the dark as to how to communicate with the service and what to expect as a response.  This results in a lot of trial-and-error and having to manually write code to marshall & unmarshall the XML data.
• Web Services that define a WSDL but don't conform to it.
• This can be extremely frustrating for the Web Service consumer who usually ends up getting some sort of a cryptic error message from his generated XML bindings code.  That leads to a lot of head scratching and eventually writing the XML marshalling code from scratch.  I would say this is a worse offense than not defining a WSDL at all. 
• Web Services that are hidden behind some proprietary authentication protocol.  
• A good example that comes to mind is the NTLM v2 protocol that IIS supports and is a proprietary Microsoft protocol.  Integrating with this protocol from other technologies than .Net is usually not straight forward.  Last time I had to do it from Java we ended up having to purchase a proprietary library to be able to authenticate against the service, as no reliable open source implementation existed (which took us way to long to discover).
• Web Services that define poor or no error messages.
• These are the type of services that blow up with some XML parsing error, showing a stack trace that is specific to the Web Service implementation technology.  They basically provide no useful feedback to the consumer about what may have gone wrong and whether the issue is on the client or server side.  Furthermore, it leaves no way for the consumer to gracefully handle the error by choosing actions based on error type.
• Web Services that don't work unless consumed in the authoring technology.
• I have often I had to consume Web Services that were incorrectly autogenerated by some tool/framework (Siebel and .Net come to mind), and really don't conform to Web Service standards.  I therefore urge developers to test their own service with soapUI, JMeter or other standalone Web Service clients, before they publish it to others. That way you also get to chew your own dog food, so to speak, meaning you see what the XML for your service looks like.

That's my two cents on the issue.  If you have more guidelines to share, or don't agree with mine, I'd love to hear from you.