aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJason A. Donenfeld <Jason@zx2c4.com>2013-01-20 06:57:17 +0100
committerJason A. Donenfeld <Jason@zx2c4.com>2013-01-20 06:57:17 +0100
commitd24fd35954fa028c369b10ec6b9eb7251f2e7cda (patch)
treeb22b75c450bb38e0af6b1446fd9a395e243408fc
parentNormalize on 4 spaces instead of tabs. Clean up language and formatting. (diff)
downloadramc-spec-d24fd35954fa028c369b10ec6b9eb7251f2e7cda.tar.xz
ramc-spec-d24fd35954fa028c369b10ec6b9eb7251f2e7cda.zip
Normalize headers.
-rw-r--r--spec.md42
1 files changed, 21 insertions, 21 deletions
diff --git a/spec.md b/spec.md
index ce7a283..6b50967 100644
--- a/spec.md
+++ b/spec.md
@@ -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."