Skip to content

Latest commit

 

History

History
148 lines (101 loc) · 4.02 KB

API.md

File metadata and controls

148 lines (101 loc) · 4.02 KB

The backend API

This document describes the API used to serve chords from the database to the frontend.

Note: this is a v0 API, hence it is subject to breaking changes at any time without warning.

API endpoints

GET /api/v0/artists

Returns a list of all artists in the database.

Response body

A list of strings representing artist names.

*This data is autogenerated from the songs in the database. Hence, there is no need for POST, PUT, or DELETE methods for the /api/v0/artists endpoint.

GET /api/v0/songs

Returns all songs matching the given query.

Query parameters

Name Required? Description
artist optional If provided, the response will contain songs by the given artist.
id optional If provided, the response will only contain the metadata for the song with the given ID.
query optional If provided, the response will contain songs whose names match the search query.

If no query parameters are provided, then this method will return all songs in the database.

Response body

A list of SongMeta objects.

POST /api/v0/songs

This method requires authorisation.

Add a new song to the database.

NB: this method only initialises the metadata - after receiving the new song ID, make a separate call to PUT /api/v0/chords to provide the chords.

Request body

A SongMeta object describing the metadata of the new song to be created. There is no need to set the id field, as this will be automatically assigned upon creation.

Response body

A SongMeta object describing the metadata of the newly created song. This will include the new song ID.

PUT /api/v0/songs

This method requires authorisation.

Update the metadata for a song in the database.

Query parameters

Name Required? Description
id required The ID of the song to update metadata for.

Request body

A SongMeta object describing the new metadata for this song. The id field will be ignored. All other fields will be set to the provided values (and dropped if no value is provided).

Response body

A SongMeta object describing the updated metadata for this song.

DELETE /api/v0/songs

This method requires authorisation.

Delete a song from the database. The song's chords will also be deleted.

Query parameters

Name Required? Description
id required The ID of the song to delete.

GET /api/v0/chords

Returns the chords for a given song.

Query parameters

Name Required? Description
id required The ID of the song to retrieve chords for.

Response body

The requested chords, in plain-text format.

PUT /api/v0/chords

This method requires authorisation.

Updates the chords for a given song.

Query parameters

Name Required? Description
id required The ID of the song to update chords for.

Request body

The new chords for this song, in plain-text format.

Response body

The updated chords for this song, in plain-text format.

*Each instance of the chords resource type is tied to an instance of the songs resource type. Hence, there is no need for POST or DELETE methods for the /api/v0/chords endpoint - just use the corresponding method for /api/v0/songs.

GET /api/v0/see-also

Returns other artists related to a given artist.

Query parameters

Name Required? Description
artist required The artist for which to get related artists.

Response body

A list of strings representing artist names.

API types

SongMeta

Describes metadata for a song. The format is like this:

{
  // Unique ID assigned upon creation in DB
  "id":      1037,
  "name":   "Your Song",
  "artist": "Elton John",
  "album":  "Elton John",
  // The position of this song on the album 
  "trackNum": 1
}