path: root/spec.md

# [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 (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](http://git.zx2c4.com/zmusic-ng/about) and [Beets](http://beets.radbox.org/), with many more apps to come.

![RAMC Logo](http://git.zx2c4.com/ramc-spec/plain/logo.png)

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.

### <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 (as specified by `<object type>`) matching the specified `<search query>`. If the query is omitted, returns all objects in the system.

#### The Query String

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.

#### 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`.

##### <a name="songs"></a> 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](#mimetypes) of the underlying file.
* `title`: The title of the song.

Other keys may also be included; for example:

* `album`
* `artist`
* `length`
* `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",
				"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>`

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",
						"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>`

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",
								"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 `Accept:` 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

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](#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>

## Errors

For any successful request, the server responds with HTTP status 200 and the result dictionary 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 what went wrong. For example, when an invalid token in supplied to an authenticated endpoint, the server could respond with HTTP status 403 and the following body:

    {
        "error": "authentication error"
    }

## License
This work is licensed under the [Creative Commons Attribution-ShareAlike 3.0 Unported License](http://git.zx2c4.com/ramc-spec/tree/COPYING).