This guide is designed to simplify migrating your code from Spotify Apps API 0.x to 1.0.

Changes of Note in Apps API 1.0.0

Most changes focus on a better split of the API into modules and an async approach to fetch only the information that is needed in each moment, decreasing network usage and make the API suitable for platforms in which this is key to offer the best experience.

JS Framework

Requiring modules in the JS Framework

The way of requiring framework modules has changed and now they are retrieved using a require function. Views have been split in different modules, so now you need to specify the suitable one for the views elements you are using. So, if you are using, for instance, models and views for using an Image view you will change:

var sp = getSpotifyApi(),
    models = sp.require("$api/models");
    views = sp.require("$api/views");

or the older:

var sp = getSpotifyApi(1),
    models = sp.require("sp://import/scripts/api/models");
    views = sp.require("sp://import/scripts/api/views");

to this one:

require(['$api/models', '$views/image#Image'], function(models, Image) {
 ...
});

To find out what module each view belongs to, check the Views Framework documentation.

Retrieving data

When using models such as Track, Album, Playlist, Artist, etc, now you need to specify the attributes you want to retrieve. This way, only data that is needed is requested. Also note the usage of Promises: In order to print the uri and name of a track, you used to do:

var sp = getSpotifyApi(),
    models = sp.require("$api/models");
models.Track.fromURI('spotify:track:2M5nPOo9UmoQVOWrN8lfN1', function(track) {
  console.log(track.uri + ': ' + track.name);
});

Now that is done through this:

require(['$api/models'], function(models) {
  models.Track.fromURI('spotify:track:2M5nPOo9UmoQVOWrN8lfN1').load('name').done(function(track) {
    // uri is always present
    console.log(track.uri + ': ' + track.name);
  }).fail(function()) {
    console.error('Error trying to retrieve track');
  });
});

Snapshots

When performing operations that retrieve a set of items you will need to take a snapshot specifying the range of items you want to fetch.

In this example, we will fetch 5 tracks from an album and print their track URI and first artist URI. With the 0.x API you would do:

var sp = getSpotifyApi(),
    models = sp.require("$api/models");
var maxItems = 5;
models.Album.fromURI('spotify:album:0hljn4caZCf6xPILpLDJkB', function(album) {
  for (var i = 0, l = album.tracks.length; i < l; i++) {
    var track = album.tracks[i];
    console.log(track.artists[0].uri, track.uri);
  }
});

with 1.0.0 you do it like this:

require(['$api/models'], function(models) {
  var maxItems = 5,
      album = models.Album.fromURI('spotify:album:0hljn4caZCf6xPILpLDJkB');
  album.load('tracks', 'artists').done(function(a) {
    a.tracks.snapshot(0, maxItems).done(function(snapshot) {
      for (var i = 0, l = Math.min(snapshot.length, maxItems); i < l; i++) {
        var track = snapshot.get(i);
        console.log(track.artists[0].uri, track.uri);
    }).fail(function(){
        console.error('Error retrieving snapshot');
    });
  }).fail(function(){
      console.error('Error retrieving album information');
  });
});

Views Framework

Including stylesheets

The stylesheets have been split, so you only incude those that belong to the view elements you are using.

Before, you would have:

  <link rel="stylesheet" href="sp://import/css/shared.css">
  <link rel="stylesheet" href="sp://resources/css/eve.css">
  <link rel="stylesheet" href="sp://resources/css/api.css">

plus the ones you needed for certain view elements:

  <link rel="stylesheet" href="sp://resources/css/player.css">
  <link rel="stylesheet" href="sp://resources/css/list.css">

Now you include the ones that are called like the views module you are requiring:

  <link rel="stylesheet" href="$views/css/image.css">

The set of CSS files you can include can be found in the Views Framework documentation.

Image

Now, the Image view uses static methods to create images. In addition, the type of content is specified in the function name: From:

var sp = getSpotifyApi(),
    models = sp.require("$api/models"),
    album = models.Album.fromURI('spotify:album:2mCuMNdJkoyiXFhsQCLLqw'),
    image = new views.Image(album.image, album.uri);

to:

require(['$api/models', '$views/image#Image'], function(models, Image) {
  var album = models.Album.fromURI('spotify:album:2mCuMNdJkoyiXFhsQCLLqw'),
      image = Image.forAlbum(album);
});

Image as a Player

If you want the Image to have a play button, you can achieve it by passing an option player set to true. This replaces the Player view present in 0.x.

For instance, for creating a player for a track, instead of:

var sp = getSpotifyApi(),
    models = sp.require("$api/models"),
    views = sp.require("$api/views");
// retrieve the track
var track = models.Track.fromURI('spotify:track:0blzOIMnSXUKDsVSHpZtWL');
// create a temporary playlist with that single track
var playlist = new models.Playlist();
playlist.add(track);
// attach the playlist to the Player view
var player = new views.Player();
player.track = null; // Don't play the track right away
player.context = playlist;

you would write:

require(['$api/models', '$views/image#Image'], function(models, Image) {
  var track = models.Track.fromURI('spotify:track:0blzOIMnSXUKDsVSHpZtWL'),
      image = Image.forTrack(track, {player: true});
});