Concerto API

Returns a single recording by its ID, including its musical period and length.

• Version: 1.0.0
• Base URL: https://api.concerto.test

Endpoints

Recordings

• GET /recordings: Search recordings
• GET /recordings/{id}: Get one recording

Playlists

• POST /playlists: Create a playlist
• GET /playlists/{id}: Get a playlist
• POST /playlists/{id}/tracks: Add a recording to a playlist
• DELETE /playlists/{id}/tracks/{recording_id}: Remove a recording from a playlist

GET /recordings

Search recordings

Returns recordings in the catalogue. Filters can be combined.

Parameters

Name	In	Type	Required	Description
composer	query	string	no	Only recordings of works by this composer
period	query	string	no	Only recordings from this musical period, such as Baroque or Romantic
limit	query	integer	no	Maximum number of results (default 10)

Example request

curl 'https://api.concerto.test/recordings?composer=Bach'

Responses

200: A list of recordings

[
  {
    "composer": "J. S. Bach",
    "id": 21,
    "performer": "Clara Vance",
    "work": "Goldberg Variations, BWV 988",
    "year": 2019
  },
  {
    "composer": "J. S. Bach",
    "id": 22,
    "performer": "Northgate Chamber Players",
    "work": "Brandenburg Concerto No. 3, BWV 1048",
    "year": 2021
  }
]

GET /recordings/{id}

Get one recording

Returns a single recording by its ID.

Parameters

Name	In	Type	Required	Description
id	path	integer	yes	The recording's id

Example request

curl 'https://api.concerto.test/recordings/21'

Responses

200: Recording found

{
  "composer": "J. S. Bach",
  "duration_seconds": 2745,
  "id": 21,
  "performer": "Clara Vance",
  "period": "Baroque",
  "work": "Goldberg Variations, BWV 988",
  "year": 2019
}

404: No recording with that id

POST /playlists

Create a playlist

Creates a new, empty playlist. Add recordings to it afterwards.

Parameters

Name	In	Type	Required	Description
name	body	string	yes	The playlist's title, shown as listeners
description	body	string	no	A short note about the playlist, such as its mood or occassion

Example request

curl -X POST 'https://api.concerto.test/playlists' \
  -H 'Content-Type: application/json' \
  -d '{"description": "Gentle music for a slow start", "name": "Sunday morning baroque"}'

Responses

201: Playlist created

{
  "description": "Gentle music for a slow start",
  "id": 521,
  "name": "Sunday morning baroque"
}

400: Name is missing

{
  "error": "name is required"
}

GET /playlists/{id}

Get a playlist

Returns a playlist with its recordings, in playing order, and its total length.

Parameters

Name	In	Type	Required	Description
id	path	integer	yes	The playlist's id

Example request

curl 'https://api.concerto.test/playlists/521'

Responses

200: Playlist found

{
  "description": "Gentle music for a slow start",
  "id": 521,
  "name": "Sunday morning baroque",
  "total_duration_seconds": 3405,
  "tracks": [
    {
      "composer": "J. S. Bach",
      "duration_seconds": 2745,
      "recording_id": 21,
      "work": "Goldberg Variations, BWV 988"
    },
    {
      "composer": "J. S. Bach",
      "duration_seconds": 660,
      "recording_id": 22,
      "work": "Brandenburg Concerto No. 3, BWV 1048"
    }
  ]
}

404: No playlist with that id

POST /playlists/{id}/tracks

Add a recording to a playlist

Add a recording to the end of a playlist.

Parameters

Name	In	Type	Required	Description
id	path	integer	yes	The playlist's id
recording_id	body	integer	yes	The recording to add

Example request

curl -X POST 'https://api.concerto.test/playlists/521/tracks' \
  -H 'Content-Type: application/json' \
  -d '{"recording_id": 23}'

Responses

201: Recording added to playlist

{
  "id": 521,
  "position": 3,
  "recording_id": 23
}

404: Playlist or recording not found

409: Recording is already in the playlist

DELETE /playlists/{id}/tracks/{recording_id}

Remove a recording from a playlist

Removes a recording from a playlist. The recordings after it move up one place.

Parameters

Name	In	Type	Required	Description
id	path	integer	yes	The playlist id
recording_id	path	integer	yes	The recording to remove

Example request

curl -X DELETE 'https://api.concerto.test/playlists/521/tracks/23'

Responses

204: Recording removed

404: Playlist not found or the recording isn't in it