Stream Music – Cloud

Authentication

All requests to the Music Streaming API should be signed with an OAuth token.

Methods

GET /api/music/v2/

The root of the music streaming REST API.

Returns links for entity collections, batched and complete:

{
    "meta":
    {
        "msg": "ok",
        "status": 200
    },
    "response":
    {
        "artists_batch_url": "https://one.ubuntu.com/api/music/v2/artists/?limit=50&offset=0",
        "artists_url": "https://one.ubuntu.com/api/music/v2/artists/",
        "albums_batch_url": "https://one.ubuntu.com/api/music/v2/albums/?limit=50&offset=0",
        "albums_url": "https://one.ubuntu.com/api/music/v2/albums/",
        "songs_batch_url": "https://one.ubuntu.com/api/music/v2/songs/?limit=50&offset=0",
        "songs_url": "https://one.ubuntu.com/api/music/v2/songs/",
        "playlists_batch_url": "https://one.ubuntu.com/api/music/v2/playlists/?limit=50&offset=0",
        "playlists_url": "https://one.ubuntu.com/api/music/v2/playlists/"
    }
}
GET /api/music/v2/artists/

Get a list of artists.

Query Parameters:
 
  • limit – Integer representing the size of the batch. The server will use the initial batch size to generate subsequent batches.
  • offset – Integer representing the index of the list of all artists the batch should start with.

Returns a list of artist representations:

{
    "meta":
    {
        "status": 200,
        "msg": "ok",
        // Optional
        "total": integer (total number of artists (union of track and album artists))
        "limit": limit passed in from the query parameter,
        "offset": offset passed in from the query parameter,
        // Optional, will not appear on last batch
        "next_batch": "https://one.ubuntu.com/api/music/v2/artists/?limit=(limit)&offset=(limit + offset)",
    },
    "response":
    {
        "artists":
        [
            {
                "id": artist id,
                "artist": artist name,
                "song_count": integer (number of songs with the artist as either the track's artist or album_artist),
                "album_ids": [list of album ids],
                "artist_url": "https://one.ubuntu.com/api/music/v2/artists/(artist_id)/",
                "artist_art_url": "https://one.ubuntu.com/api/music/v2/artists/(artist_id)/art/"
            },
            …
        ]
    }
}
GET /api/music/v2/artists/(artist_id)/

Get an artist’s list of albums.

Parameters:
  • artist_id – the artist id.

Returns a list of album representations:

{
    "meta":
    {
        "status": 200,
        "msg": "ok"
    },
    "response":
    {
        "albums":
        [
            {
                "id": album id,
                "title": album title,
                "artist": album artist,
                "artist_id": artist id,
                "year": album year,
                "parsed_date": timestamp the album was processed by Ubuntu One,
                "album_url": "https://one.ubuntu.com/api/music/v2/albums/(album_id)/",
                "album_art_url": "https://one.ubuntu.com/api/music/v2/albums/(album_id)/art/",
                // Optional
                "cover_art": cover art attachment id
            },
            …
        ]
    }
}
GET /api/music/v2/albums/

Get a list of albums.

Query Parameters:
 
  • limit – Integer representing the size of the batch. The server will use the initial batch size to generate subsequent batches.
  • offset – Integer representing the index of the list of all artists the batch should start with.

Returns a list of album representations:

{
    "meta":
    {
        "status": 200,
        "msg": "ok",
        // Optional
        "total": integer (total number of albums),
        "limit": limit passed in from the query parameter,
        "offset": offset passed in from the query parameter,
        // Optional, will not appear on last batch
        "next_batch": "https://one.ubuntu.com/api/music/v2/albums/?limit=(limit)&offset=(limit + offset)",
    },
    "response":
    {
        "albums":
        [
            {
                "id": album id,
                "title": album title,
                "artist": album artist,
                "artist_id": album artist id,
                "year": album year,
                "parsed_date": timestamp the album was processed by Ubuntu One,
                "album_url": "https://one.ubuntu.com/api/music/v2/albums/(album_id)/",
                "album_art_url": "https://one.ubuntu.com/api/music/v2/albums/(album_id)/art/",
                // Optional
                "cover_art": cover art attachment id
            },
            …
        ]
    }
}
GET /api/music/v2/albums/(album_id)/
Parameters:
  • album_id – the album id.

Returns a list of song representations:

{
    "meta":
    {
        "status": 200,
        "msg": "ok"
    },
    "response":
    {
        "songs":
        [
            {
                "id": song id (file node id),
                "title": track title,
                "artist": track artist,
                "album": album title,
                "year": track release year,
                "album_artist": album artist (can differ from track artist),
                "artist_id": album artist id,
                "album_id": album id,
                "content_type": mime type,
                "suffix": filename suffix,
                "disc_number": disc number,
                "track": track number on album,
                "genre": primary genre,
                "duration": duration in seconds,
                "size": size in bytes,
                "bit_rate": bit rate,
                "path": file path,
                "song_url": "https://one.ubuntu.com/api/music/v2/songs/(song_id)/",
                "song_stream_url": "https://streaming.one.ubuntu.com/api/music/v2/songs/(song_id)",
                "song_art_url": "https://one.ubuntu.com/api/music/v2/albums/(song_id)/art/"
            },
            …
        ]
    }
}
GET /api/music/v2/songs/

Get a list of songs.

Query Parameters:
 
  • limit – Integer representing the size of the batch. The server will use the initial batch size to generate subsequent batches.
  • offset – Integer representing the index of the list of all artists the batch should start with.

Returns a list of song representations:

{
    "meta":
    {
        "status": 200,
        "msg": "ok",
        // Optional
        "total": integer (total number of songs),
        "limit": limit passed in from the query parameter,
        "offset": offset passed in from the query parameter,
        // Optional, will not appear on last batch
        "next_batch": "https://one.ubuntu.com/api/music/v2/songs/?limit=(limit)&offset=(limit + offset)",
    },
    "response":
    {
        "songs":
        [
            {
                "id": song id (file node id),
                "title": track title,
                "artist": track artist,
                "artist_id": track artist id,
                "album": album title,
                "year": track release year,
                "album_artist": album artist,
                "album_artist_id': album artist id,
                "album_id": album id,
                "content_type": mime type,
                "suffix": filename suffix,
                "disc_number": disc number,
                "track": track number on album,
                "genre": primary genre,
                "duration": duration in seconds,
                "size": size in bytes,
                "bit_rate": bit rate,
                "path": file path,
                "song_url": "https://one.ubuntu.com/api/music/v2/songs/(song_id)/",
                "song_stream_url": "https://streaming.one.ubuntu.com/api/music/v2/songs/(song_id)",
                "song_art_url": "https://one.ubuntu.com/api/music/v2/albums/(song_id)/art/"
            },
            …
        ]
    }
}
GET /api/music/v2/songs/(song_id)/
Parameters:
  • song_id – string containing the id of a song (its file node’s id)

This handler is currently unimplemented

GET /api/music/v2/playlists/

Get a list of playlists.

Query Parameters:
 
  • limit – Integer representing the size of the batch. The server will use the initial batch size to generate subsequent batches.
  • offset – Integer representing the index of the list of all artists the batch should start with.

Returns a list of playlist representations:

{
    "meta":
    {
        "status": 200,
        "msg": "ok",
        // Optional
        "total": integer (total number of playlists),
        "limit": limit passed in from the query parameter,
        "offset": offset passed in from the query parameter,
        // Optional, will not appear on last batch
        "next_batch": "https://one.ubuntu.com/api/music/v2/playlists/?limit=(limit)&offset=(limit + offset)",
    },
    "response":
    {
        "playlists":
        [
            {
                "id": playlist id,
                "name": playlist name,
                "song_count": number of songs on the playlist,
                "playlist_url": "https://one.ubuntu.com/api/music/v2/playlists/(playlist_id)/"
            },
            …
        ]
    }
}
POST /api/music/v2/playlists/

Create a new playlist by POSTing to the /playlists/ collection.

The request body must be a JSON document containing name and optionally song_id_list:

{
    "name": name of playlist,
    // Optional
    "song_id_list": [ list of song ids ]
}

Returns the new playlist:

{
    "meta":
    {
        "status": 201,
        "msg": "Created"
    },
    "response":
    {
        {
            "id": playlist id,
            "name": playlist name,
            "song_count": number of songs on the playlist,
            "playlist_url": "https://one.ubuntu.com/api/music/v2/playlists/(playlist_id)/"
        }
    }
}
GET /api/music/v2/playlists/(playlist_id)/

Get a playlist representation.

Parameters:
  • playlist_id – string containing the playlist id

Returns a list of song representations:

{
    "meta":
    {
        "status": 200,
        "msg": "ok"
    },
    "response":
    {
        "songs":
        [
            {
                "id": song id (file node id),
                "title": track title,
                "artist": track artist,
                "artist_id": track artist id,
                "album": album title,
                "year": track release year,
                "album_artist": album artist,
                "album_artist_id": album artist id,
                "album_id": album id,
                "content_type": mime type,
                "suffix": filename suffix,
                "disc_number": disc number,
                "track": track number on album,
                "genre": primary genre,
                "duration": duration in seconds,
                "size": size in bytes,
                "bit_rate": bit rate,
                "path": file path,
                "song_url": "https://one.ubuntu.com/api/music/v2/songs/(song_id)/",
                "song_stream_url": "https://streaming.one.ubuntu.com/api/music/v2/songs/(song_id)",
                "song_art_url": "https://one.ubuntu.com/api/music/v2/albums/(song_id)/art/"
            },
            …
        ]
    }
}
PUT /api/music/v2/playlists/(playlist_id)/

Update a playlist.

Parameters:
  • playlist_id – string containing the playlist’s id.

The request body must be a JSON document with either a name or a song_id_list:

{
    // Optional, but one or the other is required
    "name": name of playlist,
    "song_id_list": [ list of song ids ]
}

Returns an empty JSON object:

{
    "meta":
    {
        "status": 200,
        "msg": "Updated"
    },
    "response": {}
}