diff options
Diffstat (limited to 'spec.md')
| -rw-r--r-- | spec.md | 496 |
1 files changed, 496 insertions, 0 deletions
@@ -0,0 +1,496 @@ +# [REST API for Music Collections (RAMC)](http://git.zx2c4.com/ramc-spec/about) +### by Jason A. Donenfeld (<Jason@zx2c4.com>) and Adrian Sampson (<adrian@radbox.org>) + +RAMC (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](http://git.zx2c4.com/zmusic-ng/about) and [Beets](http://beets.radbox.org/), 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 JSON, unless otherwise noted. + +### <a name="query"></a> Query + +#### `GET /query/<object type>/<search query>` +#### `GET /query/<object type>` + +* [Requires authentication](#authentication) + +The `query` request returns a listing of songs, albums, or artists based on the specified `<search query>`. + +Each word of `<search query>` 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. + +Two optional query strings, `offset` and `limit` provide pagination functionality. `offset` begins listings for the `<object type>` at a 0-based record offset. `limit` limits the number of `<object type>` entries to a given length. Each returned object contains a key `total` containing the total number of records, as if `limit` nor `offset` were not specified, as well as an `offset` key containing the same value as provided via the `offset` query string parameter. + +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. To sort a key in a descending order, prefix it with `-`. All sorting is case-insensitive. + +This endpoint is specialized by `<object type>`: + +#### <a name="songs"></a> Songs: `GET /query/songs/<search query>` + +The return value is an object containing the pagination parameters, and an array assigned to the key `songs`. Each item in the array is an object containing, at the least, the a unique identifier, `id`, the original [`mimetype`](#mimetypes) of the song's file, and a `title`. It should contain an arbitrary amount of additional metadata, including `album`, `artist`, `length` (in seconds, as a floating point number), `track`, `genre`, `year`, etc. + +##### `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", + "length": 485.8514285714286, + "id": "9e414e259ce6ac962c2d60c68787f6e73d04321d" + }, + { + "album": "Jimi Hendrix & The Lonnie Youngblood Band", + "mimetype": "audio/mpeg", + "artist": "Jimi Hendrix", + "track": 2, + "title": "Whoa 'eeh", + "length": 186.25306122448978, + "id": "c96018f7503b16ef5b89d01969c96f4bf304669c" + }, + ... + ] + } + +#### <a name="artists"></a> Artists: `GET /query/artists/<search query>` + +The return value is an object containing the pagination parameters and an array assigned to the key `artists` of objects containing the name of the artist in the `artist` key. + +##### `GET /query/artists/title:Red+House` + + { + "total": 3, + "offset": 0, + "artists": [ + { + "artist": "Albert King" + }, + { + "artist": "G3" + }, + { + "artist": "Jimi Hendrix" + } + ] + } + + +The `include` query string parameter is a space separated list of additional objects to include. `songs` and `albums` are acceptable keys. The response adds respective objects to each existing artist object: + +##### `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", + "length" 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", + "length" 189.124 + "mimetype": "audio/mpeg", + "id": "9e38b12405b3a73bf8cb49876cd36b93bf9f1a17", + "track": 3 + } + ] + } + ] + }, + ... + ] + } + +#### <a name="albums"></a> Albums: `GET /query/albums/<search query>` + +The return value is an object containing the pagination parameters and an array assigned to the key `albums` of objects containing the name of each album in the `album` key, and any additional metadata about each album. + +##### `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": /* ?? */ + } + ] + } + + +The `include` query string parameter is a space separated list of additional objects to include. `songs` and `artists` are acceptable keys. The response adds respective objects to each existing album object: + +##### `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", + "length" 189.124 + "mimetype": "audio/mpeg", + "id": "9e38b12405b3a73bf8cb49876cd36b93bf9f1a17", + "track": 3 + }, + { + "title": "Red Ho Susie", + "album": "Don't Look Back", + "artist": "Albert King", + "length" 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", + "length" 189.124 + "mimetype": "audio/mpeg", + "id": "9e38b12405b3a73bf8cb49876cd36b93bf9f1a17", + "track": 3 + }, + { + "title": "Red Ho Susie", + "album": "Don't Look Back", + "artist": "Albert King", + "length" 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. + +### <a name="files"></a>Song Files + +#### `GET /song/<id>.<ext>` +#### `GET /song/<id>` + +* [Requires authentication](#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](#mimetypes), or a [transcodable extension](#mimetypes). If the second form is used, which lacks the `<ext>` parameter, the original format will be returned, unless the HTTP `Accepts:` header provides a [transcodable mimetype](#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](#mimetypes). +* The `Content-Type` HTTP header must be set to the [correct mimetype](#mimetypes). +* 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. + +### <a name="zip"></a> Zip Bundles + +#### `POST /zip` + +* [Requires authentication](#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](#mimetypes). + +* 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`. + +### <a name="login"></a> 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](#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 + } + +### <a name="admin"></a>Administrative Functionality + +The following administrative interfaces are optional, but recommended. + +#### `GET /scan` + +* [Requires authentication](#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](#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](#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" + } + ] + } + ] + } + +## <a name="authentication"></a>Authentication + +All endpoints that require authentication may authenticate through one of the following methods: + +* A correct username and password to `username` and `password` query strings, respectively. +* A [valid token](#login) to the `token` query string parameter. +* A [valid token](#login) to the `token` HTTP cookie key. + +Endpoints that require authentication but are not authenticated shall return `HTTP 403 Access Denied`. + +## <a name="mimetypes"></a>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. + +<table> +<thead><tr><th>Name</th><th>Extension</th><th>Mimetype</th></tr></tr></thead> +<tbody> +<tr><td>Ogg Vorbis</td><td>.ogg, .oga</td><td>audio/ogg; codecs=vorbis, audio/ogg, audio/vorbis, application/ogg, audio/x-vorbis, audio/x-ogg, application/x-ogg</td></tr> +<tr><td>Ogg Opus</td><td>.opus, .ogg, .oga</td><td>audio/ogg; codecs=opus, audio/opus, audio/x-opus, audio/ogg, application/ogg, audio/x-ogg, application/x-ogg</td></tr> +<tr><td>MPEG Layer III</td><td>.mp3, .mpeg</td><td>audio/mpeg, audio/mp3, audio/x-mp3, audio/mpg, audio/x-mpeg</td></tr> +<tr><td>Flac</td><td>.flac</td><td>audio/flac, audio/x-flac, application/x-flac</td></tr> +<tr><td>WAVE</td><td>.wav, .wave</td><td>audio/wav</td></tr> +<tr><td>Musepack</td><td>.mpc</td><td>audio/x-musepack, audio/x-mpc</td></tr> +<tr><td>Windows Media Audio</td><td>.wma, .asf</td><td>audio/x-ms-wma, audio/x-ms-asf, audio/x-wma</td></tr> +<tr><td>Advanced Audio Codec</td><td>.m4a, .aac, .mp4</td><td>audio/mp4, audio/x-m4a, audio/mpeg4, audio/aac</td></tr> +<tr><td>WebM</td><td>.webm, .mka, .mkv</td><td>audio/webm</td></tr> +</tbody> +</table> + +## License +This work is licensed under the [Creative Commons Attribution-ShareAlike 3.0 Unported License](http://git.zx2c4.com/ramc-spec/tree/COPYING). |