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>
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
andlimit
: 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 keytotal
containing the total number of records, irrespective oflimit
andoffset
, as well as anoffset
key containing the same value as provided via theoffset
query string parameter. Iflimit
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 thesort
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 theinclude
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 numbertrack
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>
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 forHTTP 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 thetitle
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
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 toapplication/zip
.
Login and Logout
POST /login
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"
}
GET /login
Returns whether or not the current user is logged in and valid.
{
"loggedin": true
}
DELETE /login
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
andpassword
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.