Communication API

Valid routes

The base path for all route is /api and is not included in the tables below

GET routes:

Route	Meaning	Return type
/	Ping function	200 OK (no data)
/data	The complete data set for the application (see below)	200 OK (JSON object, see below)
/hierarchy	The folder hierarchy (see below)	200 OK (Recursive JSON object, see below)
{song}/play/{transcode?}/{bitrate?}?jwt-token={Token}	Get a media stream for the given song with optional transcoding and bitrate	media stream (depends on song)
{song}/info	Get the information about the given song	200 OK (JSON object, see below)
...

POST routes:

Route	Meaning	Body	Return type
/me	Get an authentication token	JSON object like {"email": "[email protected]", "password": "yourpw" }	200 OK (JSON object like: { "token" : "some token here"})
/settings	Set the settings for the application	JSON object like [{"key" : "value" }]	200 OK
/syncLibrary/{force?}	Trigger library re-syncing (Kutr only) with complete re-syncing if forcing	None	JSON object containing the last sync'd item after the permitted time
...

DELETE routes:

Route	Meaning	Return type
/me	Log-out	200 OK (JSON empty object)
...

Authentication

All route except /api/me require an Authorization: Bearer <TOKEN> header in the request. The <TOKEN> is create upon authentication of the user via the /api/me POST request.

You need to POST to /api/me with a JSON serialized object with key email and password.

If the email and password is found in the user's database, then the application generate a JWT token sent as JSON {"token": "the token here"}. From there, you'll replace the <TOKEN> part in the Authorization: Bearer <TOKEN> with the one returned.

Logout happens when calling /api/me with DELETE verb.

Hierarchy data format (Kutr only)

When asking for the folder hierarchy via a GET /api/hierarchy, you'll receive a recursive JSON encoded object containing the list of folder and songs.

In order to limit the data to the minimum, the format is laid out like this, starting from the root item whose name is Media Library. Basic item in the recursive set:

{ 
   "name" : "Folder name encoded in UTF-8 (or song title in UTF-8 for songs)",
   "song_id" : "The song ID if this item refers to a song (else the key is not present)",
   "children" : [
      <more items here if this items refers to a folder (else the key is not present)>
   ]
}

This recursive structure is easy to parse.

Data format

The main application data is received via a GET /api/data. You'll receive a JSON serialized object like this one (comments are between <>):

{
   "genres": [
     <Kutr only>
     { "id" : xxx <The genre identifier as integer>,
       "name" : "Genre name for this id"
     },
     <... for all genres ...>
   ],
   "artists": [
     { "id" : xxx <The artist identifier as integer>,
       "name" : "The artist name in UTF-8",
       "image": "The cover file name (URL to the picture)" or null,
       "albums": [ 
          { "id" : xxx <The album identifier as integer>,
            "artist_id" : xxx <The same identifier as the artist above, an album can have multiple artist>
            "name": "The album name in UTF-8",
            "year": xxx <The album year as integer or null>,
            "cover": "The cover file name (URL to the picture)" or null,
            "is_compilation": true / false,
            "created_at" : <This field should be removed>
            "songs" : [
               { "id" : "song id as string",
                 "album_id": xxx <The same identifier as the album above>,
                 "contributing_artist_id": null or xxx,
                 "genre_id": xxx,
                 "title": "song title",
                 "length": <duration of songs in seconds (floating point value) >,
                 "track": xxx <The track number on the album>,
                 "disc": xxx or null <The disc number on the album>,
                 "created_at": <This field should be removed>
               }
            ]
          }
       ]
     }
   ],
   "settings":
      { "media_path": "/path/to/your/Music"
   },
   "playlists": [
      <TODO document this>
   ],
   "interactions": [
      { "song_id": "some songs id",
        "liked": true / false,
        "play_count": xxx <The number of times the song was played>
      },
      <... for all songs played... >
   ],
   "users": [
      { "id": xxx <The user id as integer>, 
        "name": "User name",
        "email": "User email", 
        "is_admin": true / false, 
        "preferences": 
           { "lastfm_session_key": "hidden"},
      }
   ],
   "currentUser": 
      { <copy of the currently logged-in user object>
      },
   "useLastfm": true/false,
   "useYouTube": true/false,
   "useiTunes": true/false,
   "allowDownload": true/false,
   "cdnUrl": "your server or CDN URL",
   "currentVersion": "vX.Y.Z",
   "latestVersion": "vX.Y.T"
}