Webpage API

At Songbird, we're cognizant of the fact that the Web is a rapidly changing and evolving place. And if you're a web developer who has built on top of the Webpage API, we <3 you and want to try to make your life as smooth as possible.

Backwards compatibility is always a tricky balance between wanting to assure existing adopters (like yourself!) with guarantees of stability and making sure that our developers are able to innovate freely without being slowed down by having to sustain old decrepit APIs.

As such, we've adopted an N-2 model of backwards compatibility with respect to the Webpage API. What this means is that the current release (N) will be backwards compatible with the two previous releases. Until our 1.0 user release, we define release to be the latest micro release of a minor release train.

Perhaps an example is in order?

In the 0.2 minor release train, the latest micro release was 0.2.5. Similarly, in the 0.3 minor release train, the latest micro release was 0.3.1. So Songbird 0.4 will be backwards compatible with 0.2.5, and 0.3.1 (but not necessarily 0.3). We do this to ensure that security fixes, etc. made for follow-on micro releases do not mean we need to support a buggy API in 0.3 that was fixed in 0.3.1.

As we plan releases, we will announce APIs as deprecated and obsolete so that developers can plan around future obsolescence of APIs. APIs that are declared deprecated will be removed in 2 releases. APIs that are declared obsolete will be removed in the next release. Websites using deprecated or obsolete APIs can expect that the APIs will continue to function in a supported manner, but will emit Javascript warnings to warn the developer that the APIs will be going away in a future release.

Here's another example to help illustrate:

0.5 introduces an API called songbird.whizzyFeature();

in 0.6, we decide whizzyFeature() isn't so whizzy anymore, and we need to take it out. 0.6 marks songbird.whizzyFeature() as deprecated. Any use of it by a webpage dumps a warning to the Javascript error console that this feature is now deprecated and will be taken out by 0.8 in 0.7,

songbird.whizzyFeature() is marked obsolete. Similarly, any use of it dumps a warning to the error console that the feature is now obsolete and will be taken out by 0.8 in 0.8, songbird.whizzyFeature() is gone, and any call to it will fail per the usual Javascript failure path. (undefined, or missing attribute/method)

We believe this to be a good balance between offering all you website developers some guarantees as to stability of APIs allowing y'all to have adequate time to update accordingly as well as giving Songbird developers the flexibility to innovate freely. Be sure to watch the Webpage API space, watch our Developer blog, or subscribe to the mailing list (on the right hand side of this page) for updates of APIs (including new API announcements, and API deprecation/obsolescence).