It seems not a week goes by without some poor lost soul looking to me to help publish a Web service in a way which stands some chance of interoperating. I helped carefully craft guidelines published on an internal Wiki, but it says much about how we now work that policy published on an internal anything isn’t always authoritative, useful or readily available. This is especially true when dealing with people working for third party suppliers, consultancy groups, outsouring outfits and wot not, ironically the very users most Web services are targeted at. So in the interest of transparency, and to assist my moving on, here are some simple best practices you might like to follow when publishing a Web service:

WS-I Basic Profile Conformance

Although you may use other specifications yourself, don’t expect your customer to understand anything beyond SOAP 1.1 and WS-Addressing, I’d suggest using 2004/08 namespace, but most tools now understand the W3C WS-Addressing recommendation. Following the WS-I Basic Profile 1.2 is pretty much all you need, and is easily checked using the testing tools.

WSDL First

You don’t have to publish a WSDL document, but most people using Web services will expect one. Don’t entrust this task to generalised tooling such as XMLSpy, and avoid like the plague tools which generate WSDL from Java or C# which spew out WSDL almost as an afterthought which doesn’t interoperate, exposes the wrong information, and can be very brittle when recompiling or regenerating your code. Instead consider using a simplified model and some simple templating technology, such as XSLT, to generate your WSDL under your control, consistently. As an example of simple WSDL you can follow, see ThirdPartyCall.wsdl.

W3C XML Schema Patterns for Databinding Conformance

Although not obligatory, most consumers of your Web service will expect to be abstracted away from the contents of the messages being exchanged using databinding tools. WSDL which only contains XML Schema constructs offered by the W3C XML Basic Schema Patterns for Databinding specification is far likelier to interoperate with toolkits. Note very few standard schemas interoperate with databinding tools, so forget generating Java etc from the likes of SPML, HL7, OAGIS, etc wrapped up in WSDL.

XML Schema Killed Message Evolution

At some point you’ll likely as not want to make minor changes to your interface without breaking existing interactions. This is neigh impossible if you use XML Schema to describe your message contents, and care about interoperability with tools. In WSDL, you can add another operation, and in XML Schema, you can add additional elements and types, but the cleanest way is to communicate a breaking change by publishing another WSDL document with a different namespace. Yeah, I know, it sucks, but heck, we tried!

Expect to Document WS-Security

If you do use WS-Security, then follow the WS-I Basic Security Profile and expect to have to write documentation to describe the message contents, as we have for the Web21C SDK. This is the point where most customers will thank you for providing an SDK, rather than exposing description in one of the many flavors of WS-Policy containing one of the myriad of versions of assertion languages, few, if any of which, will interoperate with tools.

Of course things continue to slowly improve, and this advice will date, eventually. However, and this is really important, if you care about not wasting lots of your customers’ time and money, unless you are developing a service for a single consumer who demands them, I would strongly advise you DO NOT use WS-* at all. Stick to exposing data as simple Web pages, secured using the OAuth pattern, or similar method employed by the likes of Google Base, BT Mojo, Amazon S3, Yahoo! BBAuth, Flickr, Facebook, etc, etc. IOW what Dare said.

Technorati Tags: Web services