Server API¶

The backend webserver API consists of several REST API endpoints and a GraphQL API.

The GraphQL API is available via POST requests to the /graphql endpoint. The raw schema is documented at Schema.

For reference, the GraphQL queries executed by the frontend are available on Github.

Authentication¶

Each user is provisioned one authorization token. To authenticate with the backend, this token should be included with every request as the Authorization header, in the format Token {token_hex}.

A token can be generated for the admin user with the shell command $ repertoire token.

Sessions¶

In some situations, using an authorization token to authenticate every request. An alternative method of authentication–HTTP sessions–is available.

This method of authentication requires a CSRF token to be sent alongside all non-GET requests. The CSRF token is returned upon session creation.

See Sessions for the related API endpoints.

GraphQL Playground¶

The “GraphQL Playground” is packaged with repertoire. It provides an interactive playground to explore the schema documentation and write GraphQL queries. It can be accessed by visiting the /graphql endpoint in your browser. By default (and in production), it is disabled.

To run the “GraphQL Playground,” repertoire’s backend webserver must be run in debug mode. See Development to set up a development environment and run the backend webserver in debug mode.

Authentication¶

GraphQL resources are restricted to authenticated users. To be able to query/mutate them, the Authorization HTTP header must be configured.

The playground should look something like:

REST Endpoints¶

The REST endpoints of the API are as follows:

Sessions¶

These endpoints allow clients to generate sessions as an alternative method of authentication.

POST /api/session¶

Generate and return a new session.

Returns the user’s CSRF token as the response body. The response has the following format:

{
  "csrfToken": "hex-encoded token"
}

Request Headers

Authorization – An authorization token.

Status Codes

201 Created – Successfully generated a session.
401 Unauthorized – Invalid authorization token.

DELETE /api/session¶

Delete the session cookie of the requesting user.

As our cookies are HTTPOnly, clients cannot delete their own sessions. Thus, we must expose this endpoint.

Status Codes

200 OK – Successfully deleted the session.

File Serving¶

These endpoints serve the music and image files stored on the backend.

GET /api/files/images/(id)¶

Returns an image stored on the backend.

Parameters

id – The ID of the image to fetch.

Query Parameters

thumbnail – Whether to return a thumbnail (300x300) version of the image.

Request Headers

Authorization – An authorization token.

Status Codes

200 OK – Image exists and is returned.
404 Not Found – Image does not exist.

GET /api/files/tracks/(track_id)¶

Returns a track’s audio file.

Parameters

track_id – The ID of the track to fetch.

Request Headers

Authorization – An authorization token.

Status Codes

200 OK – Audio file exists and is returned.
404 Not Found – Track or audio file does not exist.