diff --git a/API.md b/API.md index 5692116..3290a03 100644 --- a/API.md +++ b/API.md @@ -1,6 +1,7 @@ # Scrobbling -In order to scrobble from a wide selection of clients, you can use Maloja's standard-compliant APIs with the following settings: +Scrobbling can be done with the native API, see [below](#submitting-a-scrobble). +In order to scrobble from a wide selection of clients, you can also use Maloja's standard-compliant APIs with the following settings: GNU FM |   ------ | --------- @@ -41,7 +42,7 @@ The user starts playing '(Fine Layers of) Slaysenflite', which is exactly 3:00 m * If the user ends the play after 1:22, no scrobble is submitted * If the user ends the play after 2:06, a scrobble with `"duration":126` is submitted * If the user jumps back several times and ends the play after 3:57, a scrobble with `"duration":237` is submitted -* If the user jumps back several times and ends the play after 4:49, two scrobbles with `"duration":180` and `"duration":109` should be submitted +* If the user jumps back several times and ends the play after 4:49, two scrobbles with `"duration":180` and `"duration":109` are submitted @@ -54,11 +55,26 @@ The native Maloja API is reachable at `/apis/mlj_1`. Endpoints are listed on `/a All endpoints return JSON data. POST request can be made with query string or form data arguments, but this is discouraged - JSON should be used whenever possible. No application should ever rely on the non-existence of fields in the JSON data - i.e., additional fields can be added at any time without this being considered a breaking change. Existing fields should usually not be removed or changed, but it is always a good idea to add basic handling for missing fields. + +## Submitting a Scrobble + +The POST endpoint `/newscrobble` is used to submit new scrobbles. These use a flat JSON structure with the following fields: + +| Key | Type | Description | +| --- | --- | --- | +| `artists` | List(String) | Track artists | +| `title` | String | Track title | +| `album` | String | Name of the album (Optional) | +| `albumartists` | List(String) | Album artists (Optional) | +| `duration` | Integer | How long the song was listened to in seconds (Optional) | +| `length` | Integer | Actual length of the full song in seconds (Optional) | +| `time` | Integer | Timestamp of the listen if it was not at the time of submitting (Optional) | +| `nofix` | Boolean | Skip server-side metadata fixing (Optional) | ## General Structure - -Most endpoints follow this structure: +The API is not fully consistent in order to ensure backwards-compatibility. Refer to the individual endpoints. +Generally, most endpoints follow this structure: | Key | Type | Description | | --- | --- | --- | @@ -66,7 +82,7 @@ Most endpoints follow this structure: | `error` | Mapping | Details about the error if one occured. | | `warnings` | List | Any warnings that did not result in failure, but should be noted. Field is omitted if there are no warnings! | | `desc` | String | Human-readable feedback. This can be shown directly to the user if desired. | -| `list` | List | List of returned [entities](#Entity-Structure) | +| `list` | List | List of returned [entities](#entity-structure) | Both errors and warnings have the following structure: @@ -87,7 +103,7 @@ Whenever a list of entities is returned, they have the following fields: | Key | Type | Description | | --- | --- | --- | | `time` | Integer | Timestamp of the Scrobble in UTC | -| `track` | Mapping | The [track](#Track) being scrobbled | +| `track` | Mapping | The [track](#track) being scrobbled | | `duration` | Integer | How long the track was played for in seconds | | `origin` | String | Client that submitted the scrobble, or import source | @@ -118,7 +134,7 @@ Whenever a list of entities is returned, they have the following fields: | Key | Type | Description | | --- | --- | --- | -| `artists` | List | The [artists](#Artist) credited with the track | +| `artists` | List | The [artists](#artist) credited with the track | | `title` | String | The title of the track | | `length` | Integer | The full length of the track in seconds |