REST API Design

File.md

Authorization

Authorizing via the "authorization" header in the request is perfect. All request definitions below do not explicitly include that header, however it should be used.

Artist

Retrieve all artists (paginated)

Definition

curl -X GET /api/artist/?page=1

Example Response

[
    // Array of artist structures sorted alphabetically and paginated to 30 per request
    // Use the same data structure as the single artist endpoint below, however...
    // only include the root and release levels, excluding the tracks
]

Retrieve an artist by name

Base Definition

curl -X GET /api/artist/{name}

Optional Parameters

curl -X GET /api/artist/{name}/?releases=1
curl -X GET /api/artist/{name}/?releases=1&tracks=1

Example Response

{
    // Name of the artist (if single)
    "name": "Artist Name",

    // Name of the artist (if many)
    "name": ["Primary Artist", "Supporting Artist"],

    // Full URL of the artist's avatar image (if available)
    "avatar": "https://...",

    // Any other relevant information regarding the artist (date joined, genre etc.)

    // If the releases parameter is passed
    "releases": [
        {
            // Unique ID of the release (unique across artists, releases and tracks)
            "id": "kc0yuj0yvno",

            // Title of the release
            "title": "Release Name",

            // Artists in the release
            "artists": ["Primary Artist", "Supporting Artist"],

            // Release label name
            "label": "Label Name",

            // Release sales start date
            "sales_start_date": "2018-05-31",

            // Release C line
            "c_line": "Release C Line",

            // Release P line
            "p_line": "Release P Line",

            // Explicit content flag
            "explicit": false,

            // Full URL to the release cover art
            "cover_art": "https://...",

            // Array of the release genres
            "genres": ["Alternative", "Ambient"],

            // Date of when the release was released
            "released_at": "2018-05-31",

            // Any other relevant information regarding the release

            // If the tracks parameter is passed
            "tracks": [
                {
                    // Unique ID of the track (unique across artists, releases and tracks)
                    "id": "mcyrb89ryp9",

                    // Title of the track
                    "title": "Name of the track",
                    "title_version": "Version of the title",

                    // Full URL to the track's cover art
                    "cover_art": "https://...",

                    // Track level artists
                    "artists": ["Primary Artist", "Supporting Artist"],

                    // Full URL of the streamable audio file
                    "audio_path": "https://...",

                    // Any other relevant information regarding the track (genre, supporting artists etc.)
                }
            ]
        }
    ]
}

Release

Retrieve an release by unique reference

Base Definition

curl -X GET /api/release/{reference}

Optional Parameters

curl -X GET /api/release/{reference}/?tracks=1

Example Response

{
    // Unique ID of the release (unique across artists, releases and tracks)
    "id": "kc0yuj0yvno",

    // Title of the release
    "title": "Release Name",

    // Artists in the release
    "artists": ["Primary Artist", "Supporting Artist"],

    // Release label name
    "label": "Label Name",

    // Release sales start date
    "sales_start_date": "2018-05-31",

    // Release C line
    "c_line": "Release C Line",

    // Release P line
    "p_line": "Release P Line",

    // Explicit content flag
    "explicit": false,

    // Full URL to the release cover art
    "cover_art": "https://...",

    // Array of the release genres
    "genres": ["Alternative", "Ambient"],

    // Date of when the release was released
    "released_at": "2018-05-31",

    // Any other relevant information regarding the release

    // Artist information (inherited)
    "artist": {
        // Fill this with the same data that the artist endpoint would return (but only the root level and excluding any relationships)
    },

    // If the tracks parameter is passed
    "tracks": [
        {
            // Unique ID of the track (unique across artists, releases and tracks)
            "id": "mcyrb89ryp9",

            // Title of the track
            "title": "Name of the track",
            "title_version": "Version of the title",

            // Full URL to the track's cover art
            "cover_art": "https://...",

            // Track level artists
            "artists": ["Primary Artist", "Supporting Artist"],

            // Full URL of the streamable audio file
            "audio_path": "https://...",

            // Any other relevant information regarding the track (genre etc.)
        }
    ]
}

Track

Retrieve a track by unique reference

Base Definition

curl -X GET /api/track/{reference}

Example Response

{
    // Unique ID of the track (unique across artists, releases and tracks)
    "id": "mcyrb89ryp9",

    // Title of the track
    "title": "Name of the track",
    "title_version": "Version of the title",

    // Full URL to the track's cover art
    "cover_art": "https://...",

    // Track level artists
    "artists": ["Primary Artist", "Supporting Artist"],

    // Full URL of the streamable audio file
    "audio_path": "https://...",

    // release information (inherited)
    "release": {
        // Fill this with the same data that the release endpoint would return (but only the root level and excluding any relationships)
    },

    // Any other relevant information regarding the track (genre, supporting artists etc.)
}