In a world where people are making interdependent webservices, API design and maintenance is pretty important. Unfortunately despite rising use and availability of APIs, there are significant problems with the way even big API vendors are deploying and maintaining their APIs.

What are a few simple rules for providing a web API?

1. Keep it clean and simple
2. Stick to standards
3. Make it about data
4. Keep it working
5. Design for updates

Keeping it clean and simple is subjective and a matter of audience. For most developers a simple API is REST/HTTP based, with XML delivery of a known or simple schema, RSS being a good general choice. For JavaScript developers or plugin writers JSON feeds might be preferrable. For enterprise development scenarios, SOAP over HTTP might be better, but generally it’s best to stick with just REST + XML/RSS.

Simple also means don’t be too abstract. Flickr for example chooses in its API to require the use of its internal ids for all API calls. This means for example that every call to find information about a user requires a call first to find the internal id of the user. Del.icio.us on the other hand just requires visible names, in fact internal ids are hidden everywhere.

Sticking to standards is a matter of developing APIs that can plug in to accepted norms. Not only does this make development easier, it makes tooling and other peripheral services work better, and generally standards are written for a good reason. Using REST? Don’t use GET requests to update state, such as in del.icio.us’s urls to delete or add urls like https://api.del.icio.us/v1/posts/add?. Using RSS? Try to stick to mainstream semantically appropriate elements rather than new namespaces, provide well formed XML, don’t stick data in XML attributes, etc.

Make it about data. Leave application design to the application developer. Google’s new Ajax search results API is a good example of an API that isn’t about data, which makes less flexible to build upon. Instead of providing JSON feeds for plugin developers, Google has chosen to build out their own little search results box, with controls and results that cannot be styled, instead of leaving the interface and logic up to the Javascript developer or plugin writer. A better design would have been a simple JSON feed of Google service search results, and a reference object to build an embedded results box.

Keep it working. An application developer working with remote web services should design with the consideration that the remote service can malfunction or die, but that doesnt’ mean that service providers shouldn’t prioritize keeping reliable service high on their list. On SWiK and other development projects I’ve done, every one of the APIs we use (del.icio.us, sourceforge, google, etc) have gone down or had problems, and I learned the hard way not to depend on any of them.

Make a clean upgrade path. There’s no permanent APIs: add a version number and keep developers informed. Flickr calls don’t have a version number but they should. In del.icio.us even browser bookmarklets have versions. Salesforce.com, whose bottom line depends on web service APIs, uses versioned WSDLs. Each new rev of Salesforce.com’s APIs are given a unique WSDL and the backend from that point is kept stable once the WSDL has been issued. This has come into practice because just like native APIs, customers started to build code against buggy behavior, and when the server logic was updated to fix bugs, their code broke. Now if there’s broken code it stays in place, and developers migrate to new services at regular and scheduled intervals.

Recently del.icio.us updated their post API to use a secure encrypted URL, so as not to betray passwords or bookmarks in cleartext if they were posted using the API. A good move, especially as developers are using GET requests to post bookmarks, which may be prompting some routers to cache sensitive user data. Yahoo was nice enough to provide clear documentation and plenty of warning about the change though. After a few months of warning, the old insecure URL was turned off, and legacy requests are redirected to the secure URL, all in all a very good update.

On the other hand, del.icio.us recently updated their rss feed of recent bookmarks: http://del.icio.us/rss to be a bit more ‘digg-esque’. Instead of showing the steady stream of users adding bookmarks to their accounts, it now aggregates the popular urls, showing you something that is currently being bookmarked quite a bit. Well guess what? LiveMarks uses those front page rss feeds to aggregate del.icio.us bookmarking activity. The RSS feed change, which was completely unannounced, significantly impacted that application, and I wish they had given some warning that the URL was going to change, instead of silently changing it. (If you are hosting a mirror for LiveMarks and I haven’t contacted you, please change the aggregation url to http://del.icio.us/rss/recent instead of http://del.icio.us/rss/).

As a sidenote, a personal annoyance is the reluctance of service providers to provide APIs against what they consider to be their most important property: public user data.

Even though many times the data is made public in various forms, such as through RSS feeds or HTML pages, data like my favorites on Flickr or my older bookmarks on del.icio.us require authorization to access, which means as a developer the interface and code needs to be more complicated to use these APIs. The new Google Ajax Search API for example requires a separate API key I must apply for, I can’t use the Google search API key I use normally.

If I want to build an application for del.icio.us for example to offer a cool visualization of all your bookmarks, and you in context of other people who are close to your bookmarking activities, it’s essentially impossible without everyone volunteering their username and password in the clear to me, data about your bookmarks in del.icio.us is behind a firewall unless you sit on the RSS feed and store the aggregation. It’s the same with last.fm, who don’t even offer an API to recover your listening data (which is why I built a last.fm proxy). It’s up to del.icio.us or the service provider as to what they want to offer, but from the developer perspective, a lot of gratuitous authorization and api keys are essentially just another barrier to building the application I am interested in building.