Windows Live Writer Beta 2 | Home | RESTful Revert

Filed under Thoughts on June 11, 2007 by Tim Meaney

Let's Stay In Touch

I've been thinking a lot lately about web services, particularly API versions, and how to make sure your software (which in 2007 is likely comprised of many disparate services) stays current with those services. More specifically - how you as creator and maintainer of your software stay current with those services. I should start off by saying that the overall goal across versions of an API is to remain backwards compatible, but for one, that isn't always the case, and new non-destructive features are frequently added in new versions. However, both cases are plagued with the same communication issue, which is described in this post.

Some background:

For one of our clients, we've built a software platform comprised of many distinct and protected services. This was done for many reasons, not the least of which is keeping a team of 15 developers productively working without stomping on each others toes, or code, as it were. You know, the whole reason we moved toward services in the first place, as a natural evolution of functions, components and objects. This particular software platform is built upon at least a dozen distinct services (however this is a bit arbitrary as a few of these are full-blown REST API implementations, which themselves are comprised of dozens of resources, each with their own life-cycle and potential effects on the API.) Most of these are created and maintained internally, but a few are commercial services. So flash-forward to this morning, imagine you're a developer coming to work on this software platform, how can you be sure your code is safe today, when you have little to no idea when they may be releasing a new version?!

This communication challenge exists within your organization as well, possibly to a greater extent than externally. Your private services likely change far more often, with undoubtedly a lesser focus on API compatibility, than those services available commercially. The good news - a new version of a service you rely on is available after being released by a guy in the cube next to you; the bad news - he forgot to let you know.

In addition to potential breakage resulting from a change to a relied-upon service, the same holds true for additions to the API. The goal across API versions is to attempt to be backwards-compatible, knowing that there are many clients out there using the services. But many times, non-destructive new services, alternate representations or additional resources are introduced that you might be interested in taking advantage of - but how will you be made aware of these?

Currently, most commercial services are described in static HTML pages, and sometimes machine-readable WADL or WSDL - but should you as a developer need to bookmark that page and check it every day? How about every week? New versions of services are sometimes announced via blogs or mailing-list, but this is 2007, every developer has a feed reader, right?

Wouldn't it be great, or at least really useful, if every service, whether private or commercial, SOAP or REST, would expose an RSS feed for each resource or method? As a part of the standard development / release process, developers can either write, or auto-generate out, information to this feed about changes to the API for new versions as they occur. Standard practice would be to create this feed for every API change, and standard practice for integrating with a service would be to subscribe to its change feed.

Picture yourself as a developer in this new world, launching your feed reader when you come in to work:

• Joel Spolsky has a new post announcing his new book on recruiting talent: awesome.
• Nick Carr has a new post letting you know it's too hot to blog, and he'll see you in a few months: damn.
• A new version of the Yahoo! Maps Traffic API now supports serialized PHP output: sweet, I can use that.
• A new version of the Highrise API now supports GET of people tagged with a specific tag: cool, that's useful!
• The guy in the cube next to you has a new version of a list of contacts service you consume, which he states is backwards compatible and isn't announcing anything particularly interesting to you.

This allows developers on both sides of a service to stay in touch, via the standard method of, well, staying in touch these days.

Post a Comment Digg Del.icio.us

Post a Comment:

Name:

Email Address:

URL:

Comment:

Windows Live Writer Beta 2 | Main | RESTful Revert