API interface - PatrickF1/GraceTunes GitHub Wiki

API inspired by https://github.com/stickfigure/blog/wiki/How-to-(and-how-not-to)-design-REST-APIs

Authentication

Authentication is done through the existing OAuth flow completely handled. Once the user is authenticated, the backend will return two cookies. One is in cleartext and has the user's current name, role, and email. The other is used for authentication and should be sent along with all API requests.

V1 API

base path = /api/v1

Songs

View song

GET /songs/:id

Query params: only one of these can apply at a time

  • sheet_format: 'nashville', 'no_chords'
  • key

Returns the song as a JSON object.

Create song

POST /songs

The song object should be stored under "song". Ideally, headers would include a CSRF token from the cookie to prevent request forgery. But we can skip this for now.

Returns the song as a JSON object.

Edit song

PUT /songs

The updated song object should be stored under "song". Returns the song post-modification as a JSON object.

Search songs

GET /songs

Query params

  • query: user search query
  • key: preferred key, no filtering by key if unspecified
  • tempo: tempo, no filtering by tempo if unspecified
    • 'Slow', 'Medium', or 'Fast'
  • sort_by: sorts results
    • can be 'created_at' (desc), 'views' (desc), or 'name' (asc)
    • defaults to relevance (desc)
  • page_num: page number, used for pagination
    • defaults to 1
  • page_size: numbers of songs to return per page
    • defaults to 10

Returns a JSON object

  • data: an array of the matching songs JSON objects
  • total_count: number of songs
  • filtered_count: number of songs after filtering

Delete song

DELETE /songs/:id

Returns 204 no content on success

Audits

Song history

GET /audits/songs/:id

Return list of up to 100 of the most recent audits for the song

Global song history

GET /audits/songs

Query params

  • action_type: no filtering by action if unspecified
    • can be 'create', 'update', 'delete'
  • page_num, defaults to 1 if unspecified
  • page_size, defaults to 20 if unspecified

Return a JSON object

  • data: an array of the matching audit JSON objects
  • total_count: number of total audits
  • filtered_count: number of audits after filtering