REST API for Music Collections (RAMC)

by Jason A. Donenfeld (Jason@zx2c4.com) and Adrian Sampson (adrian@radbox.org)

RAMC (REST API for Music Collections; pronounced "ram-see", like the Pharaoh) is a simple REST API for accessing music collections in a standard unified way. Servers implement RAMC, and various clients -- web pages, smartphone apps, desktop programs -- talk RAMC with servers. It is currently in use by ZX2C4 Music and Beets, with many more apps to come.

TODO: find real logo

This draft standard will be codified into version 1.0 on February 28th, 2013. For suggestions, amendments, modifications, or concerns, please email Jason@zx2c4.com or join #ramc on freenode for discussion.

Endpoints

All API endpoints that return a value return a JSON object unless otherwise noted.

Query

`GET /query/<object type>/<search query>`

`GET /query/<object type>`

Requires authentication.

The query request returns a listing of songs, albums, or artists (as specified by <object type>) matching the specified <search query>. If the query is omitted, returns all objects in the system.

The Search Query

Each word of <search query> in the request URL is matched as a substring against the artist, album, and title of each song. Prefixes of artist:, album:, and title:, or of any other metadata attribute, can be used to match exact strings against the respective metadata keys. * can be used as a wildcard when matches are exact. All matches, exact or inexact, are case-insensitive. Posix shell-style quoting and escaping is honored. Example searches:

charles ming
changes mingus
artist:"Charles Mingus"
artist:charles*
artist:charles* album:"Changes Two"
goodbye pork artist:"Charles Mingus"

If no <search query> is provided, all items are matched.

Optional Parameters

These endpoints support some optional parameters, which are passed as GET parameters (i.e., ?key=value).

offset and limit: These parameters provide pagination functionality. offset begins listings at a zero-based record offset. limit specifies the maximum number of records to return. The returned object contains a key total containing the total number of records, irrespective of limit and offset, as well as an offset key containing the same value as provided via the offset query string parameter. If limit is zero, then no limit is used (the default behavior).
sort: By default, items returned are sorted by artist, then year, then album, then disc, then track, and then title. Alternative sorting can be provided with the sort query string parameter which takes a space-delimited list of metadata keys by which to sort. Each key is sorted in ascending order by default. To sort a key in a descending order, prefix it with -. All sorting is case-insensitive.
include: Some object types are associated with other objects: for example, an album has constituent songs. To request that these associated objects be included, the client names them in a space-separated list for the include parameter. Each object type (below) specifies the valid include terms.

Returned Value

The JSON object returned at this endpoint has the following structure:

{
    "total": <integer>,
    "offset": <integer>,
    "<object type>": [
        <object>,
        <object>,
        ...
    ]
}

The keys of each object in the list depends on the type of object requested. The allowed object types are songs, albums, and artists.

Songs: `GET /query/songs/<search query>`

Each song object (in the songs array of the result object) contains at least these keys:

id: A unique identifier of any scalar JSON type.
mimetype: The MIME type of the underlying file.
title: The title of the song.

Other keys may also be included; for example:

album
artist
duration in seconds as a floating point number
track
genre
year

`GET /query/songs/hendrix`

{
    "total": 311,
    "offset": 0,
    "songs": [
        {
            "album": "Jimi Hendrix & The Lonnie Youngblood Band",
            "mimetype": "audio/mpeg",
            "artist": "Jimi Hendrix",
            "track": 1,
            "title": "Red House",
            "duration": 485.8514285714286,
            "id": "9e414e259ce6ac962c2d60c68787f6e73d04321d"
        },
        {
            "album": "Jimi Hendrix & The Lonnie Youngblood Band",
            "mimetype": "audio/mpeg",
            "artist": "Jimi Hendrix",
            "track": 2,
            "title": "Whoa 'eeh",
            "duration": 186.25306122448978,
            "id": "c96018f7503b16ef5b89d01969c96f4bf304669c"
        },
        ...
    ]
}

Artists: `GET /query/artists/<search query>`

Each artist object must contain at least the artist key, a string naming the artist.

Two include terms are available: songs and albums. When either is used alone, each artist objects contain that key mapping to a list of all objects of that type associated with the artist. When both keys are used, the artist object contains only an albums key, which itself contains a songs key.

`GET /query/artists/title:Red+House`

{
    "total": 3,
    "offset": 0,
    "artists": [
        {
            "artist": "Albert King"
        },
        {
            "artist": "G3"
        },
        {
            "artist": "Jimi Hendrix"
        }
    ]
}

`GET /query/artists/title:Red+House?include=albums`

{
    "total": 3,
    "offset": 0,
    "artists": [
        {
            "artist": "Albert King",
            "albums": [
                {
                    "album": "Don't Look Back",
                    "albumart": /* ?? */,
                }
            ]
        },
        {
            "artist": "G3",
            "albums": [
                {
                    "album": "G3 Live in Concert",
                    "albumart": /* ?? */,
                }
            ]
        },
        {
            "artist": "Jimi Hendrix",
            "albums": [
                {
                    "album": "Are You Experienced",
                    "albumart": /* ?? */,
                }
            ]
        }
    ]
}

`GET /query/artists/title:Red+House?include=songs`

{
    "total": 3,
    "offset": 0,
    "artists": [
        {
            "artist": "Albert King",
            "songs": [
                {
                    "title": "Red House",
                    "album": "Don't Look Back",
                    "artist": "Albert King",
                    "duration" 189.124
                    "mimetype": "audio/mpeg",
                    "id": "9e38b12405b3a73bf8cb49876cd36b93bf9f1a17"
                }
            ]
        },
        ...
    ]
}

`GET /query/artists/title:Red+House?include=songs+albums`

{
    "total": 3,
    "offset": 0,
    "artists": [
        {
            "artist": "Albert King",
            "albums": [
                {
                    "album": "Don't Look Back",
                    "albumart": /* ?? */,
                    "songs": [
                        {
                            "title": "Red House",
                            "album": "Don't Look Back",
                            "artist": "Albert King",
                            "duration" 189.124
                            "mimetype": "audio/mpeg",
                            "id": "9e38b12405b3a73bf8cb49876cd36b93bf9f1a17",
                            "track": 3
                        }
                    ]
                }
            ]
        },
        ...
    ]
}

Albums: `GET /query/albums/<search query>`

Each album object must contain at least the album key, the title of the object. Other keys might include per-album metadata such as year and genre.

Two include terms are available: songs and artists.

`GET /query/albums/title:Red+Ho*`

{
    "total": 3,
    "offset": 0,
    "albums": [
        {
            "album": "Don't Look Back",
            "albumart": /* ?? */
        },
        {
            "album": "G3 Live in Concert",
            "albumart": /* ?? */
        },
        {
            "album": "Are You Experienced",
            "albumart": /* ?? */
        }
    ]
}

`GET /query/albums/title:Red+Ho*?include=songs`

{
    "total": 3,
    "offset": 0,
    "albums": [
        {
            "album": "Don't Look Back",
            "albumart": /* ?? */,
            "songs": [
                {
                            "title": "Red House",
                            "album": "Don't Look Back",
                            "artist": "Albert King",
                            "duration" 189.124
                            "mimetype": "audio/mpeg",
                            "id": "9e38b12405b3a73bf8cb49876cd36b93bf9f1a17",
                            "track": 3
                },
                {
                            "title": "Red Ho Susie",
                            "album": "Don't Look Back",
                            "artist": "Albert King",
                            "duration" 121.432
                            "mimetype": "audio/mpeg",
                            "id": "972a1a11f19934401291cc99117ec614933374ce",
                            "track": 5
                },
            ]
        },
        ...
    ]
}

`GET /query/albums/title:Red+Ho*?include=artists`

{
    "total": 3,
    "offset": 0,
    "albums": [
        {
            "album": "Don't Look Back",
            "albumart": /* ?? */
        },
        {
            "album": "G3 Live in Concert",
            "albumart": /* ?? */
        },
        {
            "album": "Are You Experienced",
            "albumart": /* ?? */
        }
    ],
    "artists": [ "Albert King", "G3", "Jimi Hendrix" ]
}

`GET /query/albums/title:Red+House?include=songs+artists`

{
    "total": 3,
    "offset": 0,
    "albums": [
        {
            "album": "Don't Look Back",
            "albumart": /* ?? */,
            "songs": [
                {
                            "title": "Red House",
                            "album": "Don't Look Back",
                            "artist": "Albert King",
                            "duration" 189.124
                            "mimetype": "audio/mpeg",
                            "id": "9e38b12405b3a73bf8cb49876cd36b93bf9f1a17",
                            "track": 3
                },
                {
                            "title": "Red Ho Susie",
                            "album": "Don't Look Back",
                            "artist": "Albert King",
                            "duration" 121.432
                            "mimetype": "audio/mpeg",
                            "id": "972a1a11f19934401291cc99117ec614933374ce",
                            "track": 5
                },
            ]
        },
        ...
    ],
    "artists": [ "Albert King", "G3", "Jimi Hendrix" ]
}

Note: the artists object for the include query string is superfluous, and exists only for the sake of completeness.

Song Files

`GET /song/<id>.<ext>`

`GET /song/<id>`

Requires authentication.

Returns the data in the music file specified by <id> in the format given by <ext>. <ext> may be the original format's preferred extension, or a transcodable extension. If the second form is used, which lacks the <ext> parameter, the original format will be returned, unless the HTTP Accept: header provides a transcodable mimetype. If a format is requested that is not the song's original format, the server will transcode it. Use of original formats by clients is preferred, to cut down on server load and to preserve quality.

If the requested format or id is unable to be returned, an HTTP 404 Not Found response shall be returned.
The Content-Range HTTP header and support for HTTP 206 Partial Response are recommended, at least for non-transcoded responses.
The Content-Disposition: attachment; filename="filename.ext" HTTP header must be sent using a filename that at least contains the title of the song and the preferred extension.
The Content-Type HTTP header must be set to the correct mimetype.
The X-Content-Duration HTTP header must be returned with the response, if duration metadata is available, containing the duration of the requested song in seconds as a floating point number.

Album Art

`GET /query/albums/<search query>/images/<index>.jpg`

Retrieve the album art for an album matching the given search query. This endpoint accepts the same pagination and sorting parameters as the above album query API. It returns the image associated with the <index>th album in the result list.

Zip Bundles

`POST /zip`

Requires authentication.

Takes arbitrary number of form parmeters with the key of id and returns a zip file containing each song using a reasonable filename containing at least the title of each song, as well as the correct extension.

The Content-Disposition: attachment; filename="filename.zip" HTTP header must be sent using a unique filename.
The Content-Type HTTP header must be set to application/zip.

Takes POST form parameters username and password. Returns whether or not login was successful, an authentication token, and sets an HTTP cookie containing that same authentication token.

Set-Cookie: token=an9292n239201128ana9a

{
    "loggedin": true,
    "token": "an9292n239201128ana9a"
}

Returns whether or not the current user is logged in and valid.

{
    "loggedin": true
}

`POST /logout`

Requires authentication, but does not accept cookie-based authentication to protect against CSRF.

Logs out the current user by invalidating the current token. Returns an object indiciating success:

{
    "loggedin": false
}

Administrative Functionality

The following administrative interfaces are optional, but recommended.

`GET /scan`

Requires authentication of administrative user, but does not accept cookie-based authentication to protect against CSRF.

Instructs the server to scan the library for changes. Returns streaming text output of current scanning operation, of Content-Type: text/plain.

`GET /logs/ips`

Requires authentication of administrative user.

Returns an object containing an array of IP addresses and rDNS host names:

{
    "ips": [
        {
            "ip": "82.235.163.40",
            "host": "paris.zx2c4.com"
        },
        {
            "ip": "65.27.203.43",
            "host": "cpe-65-27-203-43.cinci.res.rr.com"
        },
        ...
    ]
}

`GET /logs/ips/<ip address>`

Requires authentication of administrative user.

Returns an object containing an array of song downloads and zip downloads, with metadata, as well as the time as a UNIX time stamp in microseconds and the downloader's useragent. Top level items are sorted in reverse chronological order. Zip files are sorted at the top level by the timestamp of the oldest download. Second level items inside the zip file are sorted in forward chronological order.

`GET /logs/ips/82.235.163.40`

{
    "downloads": [
        {
            "song": {
                "album": "The Lord of the Rings: The Return of the King",
                "title": "The Grey Heavens",
                "ip": "82.235.163.40",
                "artist": "Howard Shore",
                "time": 135852693453491,
                "useragent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.17 (KHTML, like Gecko) Chrome/24.0.1312.52 Safari/537.17",
                "id": "3910251a03c93dd40c40156494f0f14db329d78a"
            }
        },
        {
            "song": {
                "album": "The Lord of the Rings: The Return of the King",
                "title": "The Return Of The King",
                "ip": "82.235.163.40",
                "artist": "Howard Shore",
                "time": 135852631953447,
                "useragent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.17 (KHTML, like Gecko) Chrome/24.0.1312.52 Safari/537.17",
                "id": "d12f652fb772c82b50f0006d3db45af8063711c2"
            }
        },
        {
            "zip": [
                {
                    "album": "Dialogues",
                    "title": "Stern Stuff (with Mike Stern)",
                    "ip": "82.235.163.40",
                    "artist": "Jim Hall",
                    "time": 135796967448742,
                    "useragent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.17 (KHTML, like Gecko) Chrome/24.0.1312.45 Safari/537.17",
                    "id": "06a3d18b3f9b51e55d3c978b0635b1738db99ad0"
                },
                {
                    "album": "These Times",
                    "title": "I Know You",
                    "ip": "82.235.163.40",
                    "artist": "Mike Stern",
                    "time": 135796967448919,
                    "useragent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.17 (KHTML, like Gecko) Chrome/24.0.1312.45 Safari/537.17",
                    "id": "1296c212778f8984c16ca9e71a8d9c047ff7b6c8"
                },
                {
                    "album": "Big Neighborhood",
                    "title": "Song For Pepper",
                    "ip": "82.235.163.40",
                    "artist": "Mike Stern",
                    "time": 135796967449056,
                    "useragent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.17 (KHTML, like Gecko) Chrome/24.0.1312.45 Safari/537.17",
                    "id": "13ab9d011e41f39e5d71aa34d0d9dc9cecbcb2f5"
                }
            ]
        }
    ]
}

Authentication

A server may require authentication to access some indicated endpoints. To authenticate a request, a client can provide one of three styles of credentials:

A correct username and password to username and password query strings, respectively.
A valid token to the token query string parameter.
A valid token to the token HTTP cookie key.

Endpoints that require authentication but are not authenticated shall return HTTP 403 Access Denied.

Mimetypes

The following table includes coordinated extensions and mimetypes. Preferred extensions and mimetypes are the first item in each list.. Only preferred extensions and mimetypes should be returned by the server; however, it may use alternative mimetypes for matching client requests. If there is ambuiguity when matching mimetypes, the mimetype higher on this list shall be used.

Name	Extension	Mimetype
Ogg Vorbis	.ogg, .oga	audio/ogg; codecs=vorbis, audio/ogg, audio/vorbis, application/ogg, audio/x-vorbis, audio/x-ogg, application/x-ogg
Ogg Opus	.opus, .ogg, .oga	audio/ogg; codecs=opus, audio/opus, audio/x-opus, audio/ogg, application/ogg, audio/x-ogg, application/x-ogg
MPEG Layer III	.mp3, .mpeg	audio/mpeg, audio/mp3, audio/x-mp3, audio/mpg, audio/x-mpeg
Flac	.flac	audio/flac, audio/x-flac, application/x-flac
WAVE	.wav, .wave	audio/wav
Musepack	.mpc	audio/x-musepack, audio/x-mpc
Windows Media Audio	.wma, .asf	audio/x-ms-wma, audio/x-ms-asf, audio/x-wma
Advanced Audio Codec	.m4a, .aac, .mp4	audio/mp4, audio/x-m4a, audio/mpeg4, audio/aac
WebM	.webm, .mka, .mkv	audio/webm

Errors

For any successful request, the server responds with HTTP 200 OK and the resultant object must not contain the key error. When any server-side error occurs (malformed request, authentication error, etc.), an appropriate HTTP error status is used. The result dictionary contains the key error, associated with a string describing the error. For example, when an invalid token in supplied to an authenticated endpoint, the server may respond with HTTP 403 Access Denied and the following body:

{
    "error": "Authentication error."
}

License

This work is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License.

by Jason A. Donenfeld (Jason@zx2c4.com) and Adrian Sampson (adrian@radbox.org)

Query

Songs: GET /query/songs/<search query>

Artists: GET /query/artists/<search query>

Albums: GET /query/albums/<search query>

Song Files

Album Art

Zip Bundles

Login and Logout

Administrative Functionality

Authentication

Mimetypes

Errors

Songs: `GET /query/songs/<search query>`

Artists: `GET /query/artists/<search query>`

Albums: `GET /query/albums/<search query>`