I’ve been doing a lot of work involving web services over the last year and one thing that I’ve been thinking about quite a bit is how organizations can get their web services used. Good documentation is an obvious must but there are other things as well.
First, RESTful web services are the most popular these days because they are the easiest to use. Ironically, most web services that say they are RESTful really aren’t. They are more XML-RPC REST hybrids. True REST APIs use all the HTTP methods (GET, POST, PUT, DELETE) rather than just GET to get the job done. If you look at the Flickr “REST” API it always uses the GET method regardless of if you are reading or writing data, which to be truly RESTful it shouldn’t do. The adds should be done with POST, the edits with PUT, and the deletes with DELETE. Suffice to say if you want to know more you should read the RESTful Web Services book by Leonard Richardson, Sam Ruby, and David Heinemeier Hansson. In any case, even REST hybrids are easier than SOAP IMHO. Why? They are readable and as a result make sense to humans. For example, below is a WorldCat Search API OpenSearch query
http://www.worldcat.org/webservices/catalog/search/opensearch?q=harry%20potter&wskey=[your key]
Looking at this you can see how easy it is to read. It is this readableness that makes this type of web service interaction easy to copy and mimic. It didn’t take me long to figure out the WorldCat Search API because its uses REST. (Whether or not it is truly REST or a hybrid is up for grabs in my mind.) SOAP-based web services aren’t this easy. Instead of easily being able to see what is being sent to the server SOAP requires you to package up your request as XML. Needless to say, I personally find this much more difficult to write and debug. So if I were creating a web service (which we are at UH), I’d make sure it had a REST or REST hybrid interface.
Second, think very carefully about your data output format. Many people prefer to work with JSON. Often this is because they find it easier to use than XML. While this is a personal preference, it should be noted that most major web services provide a JSON response (and also typically XML as well). Personally, JSON isn’t my cup of tea. This is probably because I’ve had heaps of XML and am comfortable working with Xpath. So JSON doesn’t do anything for me. However, my developers LOVE it particularly when building AJAX apps and if JSON isn’t available with transform XML to JSON as a matter of course.
If you are going to output your data as XML, I have a few words of advice, which may seem slightly conflicting. Make sure you look at existing XML schemas and standards for the data you are outputting. If one that matches your needs exists, use it if possible. This will help with getting your API adopted. That being said. Complex XML is often not desirable. Partially because it requires more complex knowledge of XPath to be parsed but also because tools like Yahoo Pipes don’t understand complex XML. I learned this the hard way working with the MARCXML response from the WorldCat Search API. God, I wish there was a middle ground between the brutal complexity of MARCXML and the simple stupidity of Dublin Core. The lesson if you are building your own API? Make sure the XML structure is smart enough to represent the relevant data, but not so complex as to frustrate developers. If an existing schema is insanely complex and not well adopted (particularly beyond libraryland), don’t use it, create your own.
Third, some sort of web service builder helper tool is a good idea. The WorldCat Search API and the Flickr API both have this and I think it makes the developer’s life easier because they can easily build a url and test it. The REST Module for Drupal is supposed to do this but it is either broken or I don’t know how to properly use the testing tool due to, you guessed it, lack of good documentation. I wish an web service helper tool was something we’d built into our web service at UH from the start. It may be something we have to go back and add. Only time will tell.
Overall I think these little bits of advice can help libraries develop better web services which can be adopted and used well beyond libraryland.