Web Services
I have worked on number projects that consume third party web services, and in my experiences there have been some easy to use, well documented web services and then there is the not so user friendly, undocumented kind which are the bane of any developer. So I thought it would be a good topic to write on. There are countless books, and online resources on how to develop a web service, and there are also some handy tips on how to create a good web service. However, there are few things that get missed, especially in the tips that I have come across in online resources.
Documentation!
If you’re offering a web service to be consumed by anyone other than the developers that created it, then documentation is a must. Now I’m not talking about auto generated ones that have some xml schema tossed in there for some good reading, I’m talking about the kind that someone can pick up and find answers to the majority of their questions. Nothing can be more annoying when your results are not meeting your expectations/assumptions because there is limited or no documentation on the method you’re trying to consume.
Some documentation examples, though I have not personally used these docs, there is more information on them then some of the ones I have had the privilege of reading:
- http://developer.yahoo.com/mail/docs/user_guide/index.html
- http://www.geonames.org/export/web-services.html
Testing
Most web services have a test server, however if you think that your cunning by having a different class name from live to test than you can think again! An example of one I recently came in contact with is (LIVE: webservice.className; TEST: webservice.className_test). I now have to change code anytime I switch between the live service and the test one.
Another thing with testing is to provide a temporary data store, so that any test data can be queried upon if need be to confirm everything is working as expected before pushing everything live.
