A guide to poor API management

by Stein Magnus Jodal

This is the story of libspotify, as experienced by a Spotify customer and libspotify developer for six years.

Step 1: Support your API for years

Since April 2009, libspotify has been a mostly nice–although proprietary–C library for integrating with the Spotify music streaming service, providing both music metadata and full playback capabilities. Language wrappers have been written for a plenitude of programming languages (including my own pyspotify). libspotify is integrated into numerous open source projects (including my own Mopidy), networked AV receivers, and rumour has it: even cars.

In addition to being closed source, there was another catch: in order to use it, you need the Spotify premium subscription. Speaking from my own experience supporting a project integrating with Spotify for the last six years: lots of end users upgraded to premium in order to use the projects built on top of libspotify.

Step 2: Stop accepting bug reports and stop releasing updates

In May 2012, Spotify released libspotify 12.1.51 for all supported architectures, which now even included Android.

After months of endless requests from the quickly growing hoards of Raspberry Pi users, Spotify released libspotify 12.1.103 for hardfloat armv6 on January 22 2013. The release included minor API additions, like the addition of explicit lyrics and means for accepting Spotify’s Terms of Service.

The additions in 12.1.103 never reached the other supported architectures and 12.1.51 remains the last release for those. There was no clear communication about this being the end of libspotify, releases have just ceased. libspotify has not been mentioned in a single developer blog post or developer email newsletter since.

That’s now more than three years ago.

Step 3: Create new APIs

Over the next couple of years Spotify released a new Web API and iOS and Android SDKs. Through their developer blog, they communicated quite a bit both about these and about the deprecation of the apps inside the Spotify desktop client.

Here are some pieces from their developer blog to illustrate:

The Web API grew steadily, as documented by the Web APIs changelog. Over time, its feature list improved, supporting anonymous endpoints for generic music metadata as well as OAuth protected endpoints for managing your own music collection and playlists. The only major part missing that prevented developers replacing libspotify was music playback, as the Web API only provides 30 second previews.

From what I recall of 2014 IRC discussions with Spotify employees, they had built a new much smaller library for streaming music. The iOS and Android SDKs were simply platform specific wrappers around this new playback library and the new Web API. My impression is that, after a number of beta releases, the iOS and Android SDKs seamlessly replaced libspotify on those platforms. The plan was apparently to release the new playback library for desktop too, so that it, in combination with the Web API, could replace libspotify there as well.

That was all back in 2014.

Step 4: Deprecate old APIs

At some point, Spotify deprecated their old web API, the Metadata API. There was no blog post about it and it was not mentioned in any Spotify Developer News email I’ve received in recent years. I guess they only published this fact as a note on the Metadata API web page; it is therefore hard to track down exactly when it was deprecated and how the deprecation was communicated. Anyway, it was deprecated, and the natural upgrade path was to the new Web API. Spotify even has a migration guide mapping the concepts of the Metadata API to the new Web API. All good.

In May 2015, after 28 months without a single release or any news, libspotify is officially deprecated. The communication channel of choice? A note on the libspotify web page. No post on the developer blog. No Spotify Developer News email. To be able to use libspotify, all developers have registered and requested a personal application key. To my knowledge, none of these registered library users were notified directly.

Step 5: Shut down an old API

On January 20 2016 Spotify end-of-lifed their Metadata API. I don’t know if this date was communicated on the Metadata API web page well in advance of this shutdown. There’s no blog post on the topic. There’s no news email. There’s no tweet from @SpotifyPlatform or @SpotifyStatus. I can’t find anything except users commenting on various Spotify documentation pages that the text is outdated because the API is no longer merely deprecated, but entirely shut down.

Hopefully they did publish the shutdown date ahead of time. It had a full replacement API and a migration guide. Fair and square. Nothing much to complain about here. It’s time to get porting your code to the Web API!

But frankly, I don’t really care about this Metadata API because I don’t use the Metadata API, do I?

Step 6: Break your API without warning

February 3 2016, Mopidy users start reporting “General transient error” when searching Spotify. This is a libspotify error message known as “SP_ERROR_OTHER_TRANSIENT” with error code 16. This error usually means that there is some unspecified issue with the Spotify service. We’ve actually seen it before and like its name suggests, it is indeed transient and soon goes away.

According to a series of tweets between my fellow Mopidy developer Nick Steel and @SpotifyCares it appears that the libspotify search functionality was backed by the Metadata API’s search functionality. Who knew? I’m not aware of any relation between these APIs ever being mentioned publicly. No libspotify user could possibly have known that the Metadata API shutdown would affect them.

Let’s summarize: libspotify hasn’t had any releases for three years and it was officially deprecated in May last year. But, there have been no warnings about any shutdown. The libspotify project is likely no longer staffed at all. Did someone just forget that libspotify depended on the Metadata API they were shutting down?

Many newer networked AV receivers use the Spotify Connect libraries that are exclusive to Spotify’s commercial partners. But some receivers probably still use libspotify. If so, did Spotify just break hardware sold with Spotify support as a major feature? Something that people are paying a monthly fee to use?

It seems they did!

In the Spotify Community forums there are numerous reports of broken devices and software that all have two things in common: the date the problem started occurring, and that search is the only feature that is broken.

Surely, Spotify will quickly explain themselves and fix this?

Step 7: Stay quiet

Since the API shutdown, Spotify has been very quiet. No posts on the developer blog. No email newsletter. No tweets from @SpotifyPlatform since December 1 last year.

Some users at The Spotify Community forum are quoting responses from Spotify. Most responses seem to link to the Metadata API migration docs and state that application developers must migrate. In other cases the responses point the finger at the commercial partner which only adds to the confusion.

Some of these devices may use the Metadata API directly, and in those cases the application maintainers are probably to blame. However, I’m quite certain that the libspotify search issue is responsible for a fair share of these complaints. libspotify, in contrast to the Metadata API, has never been officially shut down. The responsibility for any breakage caused by libspotify is Spotify’s alone.

What I want from Spotify

  1. Apologize to your paying customers and supporters.

  2. Get substantially better at communicating deprecations and shutdowns. We want all news, not just good news.

  3. Give us a new supported C library for audio playback. Now! Not later this year. I’ve heard that promise for three consecutive years now.

    We can live with pre-release software quality initially. Getting the library out sooner rather than later shows us that there is a road ahead for all the projects that stream music from Spotify. Let us get started making new language wrappers.

  4. Release Spotify Connect specifications and libraries.

    We want to make music players that can be controlled by the Spotify mobile app.

    We want to make music controllers that can play music on all the Spotify Connect software and hardware players we’ve invested in.

    You’ve created this technology, now let us use it.

Thanks to Nick Steel for reviewing this blog post.