Songs endpoint

The songs endpoint returns data for individual songs. The results returned can be limited and filtered based on query string parameters.

Path and method

GET /avalon/songs

Note

This path may be different depending on your REQUEST_PATH configuration setting.

Filtering Parameters

Name Required? Type Mutiple? Description
album No string No Select only songs belonging to this album, exact match, not case sensitive.
album_id No string No Select only songs belonging to this album by UUID. The UUID is expected to be formatted using hexadecimal digits or hexadecimal digits with hyphens. If the UUID is not formatted correctly error code 101 (invalid parameter type) will be returned.
artist No string No Select only songs by this artist, exact match, not case sensitive.
artist_id No string No Select only songs by this artist by UUID. The UUID is expected to be formatted using hexadecimal digits or hexadecimal digits with hyphens. If the UUID is not formatted correctly error code 101 (invalid parameter type) will be returned.
genre No string No Select only songs belonging to this genre, exact match, not case sensitive.
genre_id No string No Select only songs belonging to this genre by UUID. The UUID is expected to be formatted using hexadecimal digits or hexadecimal digits with hyphens. If the UUID is not formatted correctly error code 101 (invalid parameter type) will be returned.
query No string No Select only songs whose album, artist, genre, or name contains query. The match is not case sensitive and unicode characters will be normalized if possible before being compared (in the query and fields being compared). The query is compared using prefix matching against each portion of the album, artist, genre, or song name (delimited by whitespace).

Other Parameters

Name Required? Type Mutiple? Description
limit No integer No If there are more than limit results, only limit will be returned. This must be a positive integer. If the offset parameter is present, the limit will be applied after the offset. If the limit is not an integer error code 101 (invalid parameter type) will be returned. If the limit is not positive error code 102 (invalid parameter value) will be returned.
offset No integer No Skip the first offset entries returned as part of a result set. This must be a positive integer. This parameter does not have any effect if the limit parameter is not also present. If the offset is not an integer error code 101 (invalid parameter type) will be returned.
order No string No Name of the field to use for ordering the result set. Any valid field of the members of the result set may be used. If the order is not a valid field error code 100 (invalid parameter name) will be returned.
direction No string No Direction to sort the results in. Valid values are asc or desc. This parameter does not have any effect if the order parameter is not also present. If the direction is not asc or desc error code 102 (invalid parameter value) will be returned.

Possible error responses

Code Message key HTTP code Description
100 avalon.service.error.invalid_input_name 400 An error that indicates that the name of a field specified is not a valid field.
101 avalon.service.error.invalid_input_type 400 An error that indicates the type of a parameter is not valid for that particular parameter.
102 avalon.service.error.invalid_input_value 400 An error that indicates the value of a parameter is not valid for that particular parameter.

Success output format

{
  "warnings": [],
  "success": [
    {
      "year": 2004,
      "track": 8,
      "name": "She's a Rebel",
      "album": "American Idiot",
      "album_id": "9ff51c16-2a7a-581c-b0b6-e28f5004139f",
      "artist": "Green Day",
      "artist_id": "b048612e-1207-59f4-bbeb-ba0bc9a48cd1",
      "genre": "Punk",
      "genre_id": "8794d7b7-fff3-50bb-b1f1-438659e05fe5",
      "id": "176cdea2-eb07-59ea-a809-2c6e23198cc8",
      "length": 120
    },
    {
      "year": 2002,
      "track": 11,
      "name": "Rotting",
      "album": "Shenanigans",
      "album_id": "9ddfbc73-6519-5ddf-a493-116cf3add9e1",
      "artist": "Green Day",
      "artist_id": "b048612e-1207-59f4-bbeb-ba0bc9a48cd1",
      "genre": "Punk",
      "genre_id": "8794d7b7-fff3-50bb-b1f1-438659e05fe5",
      "id": "840d20d8-58c6-50f6-b031-2a5a1b7c6f91",
      "length": 171
    }
  ],
  "errors": []
}

Error output format

{
  "warnings": [],
  "success": null,
  "errors": [
    {
      "payload": {
        "value": -1,
        "field": "limit"
      },
      "message_key": "avalon.service.error.invalid_input_value",
      "message": "The value of limit may not be negative",
      "code": 102
    }
  ]
}