If you’ve written a web service that other clients are going to connect to, I’m willing to bet you think you’ve done a pretty good job. I would like to take a minute of your time to explore how most web services appear to the client developer. It’s not all rosy on our side of the fence, and I’m hoping that by enumerating the most common problems I come across when working with web services, your web service can avoid them.
Let’s start with content types and formats. There are precisely two formats that you should use to respond to a request that I send to your service: the format I indicate in the Accept header or the format you tell me in your documentation. What I don’t want to see is what commonly happens on two different web services that we integrate with; we send it XML messages, and in an error situation, it occasionally responds with an HTML message! This is very disconcerting, and SimpleXML doesn’t appreciate being asked to handle malformed HTML, either!
Related to this, if you are going to serve in a given format, please ensure that you provide well-formed XML/JSON/whatever. We integrate with what we affectionately call a “nearly-XML” web service. This web service returns XML that nearly parses, except for a number of wrinkles. Specifically, we have to remove some binary characters and fix some remarkably poor entity encoding. We also have to fix the character encoding of the message to UTF-8 to match the declaration. Issues like this are sloppy and do not instill confidence in your users.
If you are supporting a common format, then please do not provide additional restraints on the format that are not generally known. My particular pet peeve is when an XML based service expects the elements within a container to be in a particular order. If you insist on requiring a specific order of elements, please document this requirement! I’ve not yet seen this problem with JSON-based services, so I assume it’s related to particular XML parser used in some enterprise middleware components.
Speaking of documentation, errors need to be really well documented — ideally within the returned error. Your users have no idea why your service doesn’t accept the request, and they want a clear reason. They do not want a message that says: Unable to store entity [CLIENT] - Status -6. This is especially useless if you don’t tell us what -6 means. Nothing slows productivity more than wasting time trying to get a request to work when you don’t know what you’ve done wrong, so throw us poor client developers a bone and provide good error messages. A better error would be: Unable to store entity [CLIENT] - Status -6: Missing NAME field.
All of the issues that I’ve talked about in this article are really easy to get right, and they all point to a root cause, the developers of the web service have never consumed their own service. If there’s one thing I want you to take away from this article, it’s this. Please write an app that consumes your web service. Also, consider writing a test suite for your web service and adding a new test case for every single support ticket you have to deal with. Create a polished web service, and everyone will be talking about how awesome you are!
Of course, if you are feeling all smug because your web service doesn’t make any of these mistakes, I thank you. You are making the Web a better place for us all.
Developer Gift
As all good English people will attest, the best way to get through a long coding session is tea. Lots of tea. In that vein, may I suggest this excellent mug as the ideal gift for your developer friends. Of course, if you haven’t yet embraced good tea, I expect that you could even use this mug for coffee.
