Introduction

Please read this before exploring all endpoints.

This documenation is available in dark mode!

Protocol

Karaoke Mugen App uses a Socket.IO ver. 3 connection to handle all API requests, it also carry events about currently playing song and playlist, users updates.

The same protocol is used by Karaoke Mugen Server to provide remote control and shortener.

Each request has its associated event and is acked by the server whenever the request is fulfilled.

socket.emit('CommandName', {...}, res => {})

Anatomy of a request

Each request is populated with, if needed, credentials and a payload (body).

RequestExample
{
    // Request payload, can be of any type
    body: {}
    // JWT token (local authorization, obtained by using login endpoint)
    authorization: ''
    // JWT Token (remote authorization, KMServer)
    onlineAuthorization: ''
}

Anatomy of a response

Each answer is formatted like this { err: boolean, data?: any }. If err is true, most of the time, the error will be formatted with a numeric code (similar to what HTTP err codes can mean) and a message.

{
    err: false,
    data: {
        // ...
    }
}
{
    err: true,
    data: {
        code: 404,
        message: {
            code: 'UNKNOWN_COMMAND'
        }
    }
}

This error happens when frontend is closed or restricted and you're using an unavailable API.

{
    err: true,
    data: {
        code: 503,
        message: {
            code: 'WEBAPPMODE_CLOSED_API_MESSAGE'
        }
    }
}

This error happens if you're requesting a resource that isn't available for your user type.

If requesting an admin resource and you're a user :

{
    err: true,
    data: {
        code: 403,
        message: {
            code: 'ADMIN_PLEASE'
        }
    }
}

If requesting any resource a guest isn't supposed to access and you're a guest :

{
    err: true,
    data: {
        code: 403,
        message: {
            code: 'NO_GUEST'
        }
    }
}

Requests and response format

Requests of all endpoints will be described as contents of the body object.

Responses from all endpoints will be in the data object for the response.

Example

login.js
import { io } from 'socket.io-client';

const socket = io();

socket.emit('login', {
    body: { username: 'hello', password: 'W0rld!!!' }
}, res => {
    console.log(res);
    /*
        {
            err: false,
            data: {
                token: '',
                // ...
            }
        }
    */
});

REST API access

This allows you to send an API command through a REST endpoint, if you don't want to use websockets.

/api/command No authentication needed Frontend can be closed, restricted or open

Send a Socket API command and get its results.

Request
{
    cmd: 'getKaras',
    body: {
        body: {
            filter: 'Dragon Ball Z'
        },
    },
    authorization: 'abcdefghijkl...'
}
Response - 200 OK
See getKara response in API documentation.
Response - 500 Internal Server Error
{
    ...
}

Uploading files

Uploading files is not done through the Websocket API as it tends to overload the protocool with big files, so we use instead a REST endpoint for that.

/api/importfile No authentication needed Frontend can be closed, restricted or open

Upload a file

Send the file as a file form item.

Request
{
    file: <data>
}
Response - 200 OK
{
    originalname: 'avatar.png' // Name on the user's computer,
    filename: 'abcdefghijklmn' // Name on the server
}