diff options
author | Jason A. Donenfeld <Jason@zx2c4.com> | 2013-01-20 06:57:17 +0100 |
---|---|---|
committer | Jason A. Donenfeld <Jason@zx2c4.com> | 2013-01-20 06:57:17 +0100 |
commit | d24fd35954fa028c369b10ec6b9eb7251f2e7cda (patch) | |
tree | b22b75c450bb38e0af6b1446fd9a395e243408fc | |
parent | Normalize on 4 spaces instead of tabs. Clean up language and formatting. (diff) | |
download | ramc-spec-d24fd35954fa028c369b10ec6b9eb7251f2e7cda.tar.xz ramc-spec-d24fd35954fa028c369b10ec6b9eb7251f2e7cda.zip |
Normalize headers.
-rw-r--r-- | spec.md | 42 |
1 files changed, 21 insertions, 21 deletions
@@ -15,14 +15,14 @@ All API endpoints that return a value return a JSON object unless otherwise note ### <a name="query"></a> Query -**`GET /query/<object type>/<search query>`** -**`GET /query/<object type>`** +#### `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 Search Query +##### 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: @@ -35,7 +35,7 @@ Each word of `<search query>` in the request URL is matched as a substring again If no `<search query>` is provided, all items are matched. -#### Optional Parameters +##### Optional Parameters These endpoints support some optional parameters, which are passed as GET parameters (i.e., `?key=value`). @@ -45,7 +45,7 @@ These endpoints support some optional parameters, which are passed as GET parame * **`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 +##### Returned Value The JSON object returned at this endpoint has the following structure: @@ -61,7 +61,7 @@ The JSON object returned at this endpoint has the following structure: 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>` +#### <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: @@ -78,7 +78,7 @@ Other keys may also be included; for example: * `genre` * `year` -**`GET /query/songs/hendrix`** +##### `GET /query/songs/hendrix` { "total": 311, @@ -106,13 +106,13 @@ Other keys may also be included; for example: ] } -##### <a name="artists"></a> Artists: `GET /query/artists/<search query>` +#### <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`** +##### `GET /query/artists/title:Red+House` { "total": 3, @@ -131,7 +131,7 @@ Two `include` terms are available: `songs` and `albums`. When either is used alo } -**`GET /query/artists/title:Red+House?include=albums`** +##### `GET /query/artists/title:Red+House?include=albums` { "total": 3, @@ -167,7 +167,7 @@ Two `include` terms are available: `songs` and `albums`. When either is used alo ] } -**`GET /query/artists/title:Red+House?include=songs`** +##### `GET /query/artists/title:Red+House?include=songs` { "total": 3, @@ -190,7 +190,7 @@ Two `include` terms are available: `songs` and `albums`. When either is used alo ] } -**`GET /query/artists/title:Red+House?include=songs+albums`** +##### `GET /query/artists/title:Red+House?include=songs+albums` { "total": 3, @@ -220,13 +220,13 @@ Two `include` terms are available: `songs` and `albums`. When either is used alo ] } -##### <a name="albums"></a> Albums: `GET /query/albums/<search query>` +#### <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*`** +##### `GET /query/albums/title:Red+Ho*` { "total": 3, @@ -247,7 +247,7 @@ Two `include` terms are available: `songs` and `artists`. ] } -**`GET /query/albums/title:Red+Ho*?include=songs`** +##### `GET /query/albums/title:Red+Ho*?include=songs` { "total": 3, @@ -281,7 +281,7 @@ Two `include` terms are available: `songs` and `artists`. ] } -**`GET /query/albums/title:Red+Ho*?include=artists`** +##### `GET /query/albums/title:Red+Ho*?include=artists` { "total": 3, @@ -303,7 +303,7 @@ Two `include` terms are available: `songs` and `artists`. "artists": [ "Albert King", "G3", "Jimi Hendrix" ] } -**`GET /query/albums/title:Red+House?include=songs+artists`** +##### `GET /query/albums/title:Red+House?include=songs+artists` { "total": 3, @@ -342,8 +342,8 @@ Note: the `artists` object for the `include` query string is superfluous, and ex ### <a name="files"></a>Song Files -**`GET /song/<id>.<ext>`** -**`GET /song/<id>`** +#### `GET /song/<id>.<ext>` +#### `GET /song/<id>` [Requires authentication.](#authentication) @@ -357,7 +357,7 @@ Returns the data in the music file specified by `<id>` in the format given by `< ### <a name="zip"></a> Zip Bundles -**`POST /zip`** +#### `POST /zip` [Requires authentication.](#authentication) @@ -528,7 +528,7 @@ The following table includes coordinated extensions and mimetypes. Preferred ext ## <a name="errors"></a>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 Forbidden` and the following body: +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." |