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