api-schema.md

API Schema

Table of Contents

• Table of Contents;
• About;
• Authorization;
• Error Handling;
• Methods;
  • Is Anonymous Access Allowed;
  • Get Max Nicknames;
  • Is Console Available;
  • Get Max Toknes;
  • Authentication;
  • Reauthentication;
  • Deauthentication;
  • Get All Users Info;
  • Get User Info;
  • Get User Login;
  • Check If User Is Administrator;
  • Check If User Is Online;
  • Get User Registration Info;
  • Get User Registration Time;
  • Get User Registrar;
  • Get User Name;
  • Get User Icon;
  • Get User Nicknames;
  • Get Server Status;
  • Get Server Version;
  • Get Server Version Name;
  • Get Server Version Protocol;
  • Get Server Players;
  • Get Server Players Count;
  • Get Server Online Players;
  • Get Server Max Players;
  • Get Server Players Sample;
  • Get Server MOTD;
  • Get Server Raw MOTD;
  • Get Server Clean MOTD;
  • Get Server HTML MOTD;
  • Get Server Address;
  • Get Server Favicon;
  • Delete All Users;
  • Delete User;
  • Delete All User Nickname;
  • Delete User Nickname;
  • Update User;
  • Update User Name;
  • Update User Icon;
  • Update User Password;
  • Update User Permissions;
  • Update User Nicknames;
  • Add User Canonical Name;
  • Add User.

About

This document contains detailed description on all supported API methods and their format.

Authoriztion

If mentioned in method's description, Authorization HTTP header with user's access token must be provided. To get access token user must first authenticate with /auth API method. Some method require access token conditionally based on logic.allowAnonymousAccess configuration option's value. It's state can be queried with /anonymous-access-allowed API method.

Error Handling

If server gets invalid request it sends 4xx error to client. If something unexpected happends on the server side it sends 5xx error. Else, if user sends structurally valid but logically invalid data (e.g. invalid login and password combination) server send's back a 200 code with JSON body of the following structure:

{
    error:       string
    needRefresh: boolean
}

needRefresh field here indicates that the error reason is expired or unregistered access token sent to server. After receiving a JSON with needRefresh set to true client should try to reauthenticate using /reauth method.

Request is treated structurally invalid in the following cases:

• Missing required header;
• Required header's format is invalid;
• Missing required body;
• Required body format is invalid.

Methods

Every API method URI shown here is relative to http.apiPrefix configuration option which defaults to /api. Data interchange format is JSON. Server will respond with JSON on every structurally valid request. Request and response JSON structure is described here as TypeScript data type. The following is a complete API method list.

---

Is Anonymous Access Allowed

Returns the value indicating whether anonymous access is allowed

Request:

GET /anonym-access-allowed

Accept: application/json

Response:

{
    allowed: boolean
}

---

Get Max Nicknames

Returns maximum allowed number of nicknames per user.

Request:

GET /max-nicknames

Authorization: Bearer <access token> -- needed if anonym access isn't allowed
Accept: application/json

Response:

{
    max: number
}

---

Is Console Available

Returns a value indicating wheter server console is available. This method is for admins only.

Request:

GET /console-available

Authorization: Bearer <admin access token>
Accept: application/json

Response:

{
    available: boolean
}

---

Get Max Tokens

Returns maximum allowed number of tokens per user.

Request:

GET /max-tokens

Authorization: Bearer <access token> -- needed if anonym access isn't allowed
Accept: application/json

Response:

{
    max: number
}

---

Authentication

Used for initial token pair reception.

Request:

POST /auth

Authorization: Basic <base64 encoded login>:<base64 encoded password>
Accept: application/json

Response:

{
    access: {
        id:  string // token hex string
        exp: string // In ISO 8601 format (YYYY-MM-DDTHH:mm:ss)
    }

    refresh: {
        id:  string // token hex string
        exp: string // In ISO 8601 format (YYYY-MM-DDTHH:mm:ss)
    }
}

---

Reauthenticate

Used for access token renewal.

Request:

POST /auth

Authorization: Bearer <refresh token>
Accept: application/json

Response:

{
    access: {
        id:  string // token hex string
        exp: string // In ISO 8601 format (YYYY-MM-DDTHH:mm:ss)
    }

    refresh: {
        id:  string // token hex string
        exp: string // In ISO 8601 format (YYYY-MM-DDTHH:mm:ss)
    }
}

---

Deauthentication

Used for access and refresh token pair deactivation.

Request:

POST /deauth

Authorization: Bearer <access token>
Accept: application/json

Response:

{}

---

Get All Users Info

Returns full information on all users.

Request:

GET /users?[nicknames][icon]

Authorization: Bearer <access token> -- needed if anonym access isn't allowed
Accept: application/json

Response:

{
    login:      string
    name:       string   | null
    icon?:      string   | null // Added if <icon> URL option is set ("data:image/png;base64,...")
    nicknames?: string[]        // Added if <nicknames> URL option is set
    isAdmin:    boolean
    isOnline:   boolean

    reg: {
        time:   string          // In ISO 8601 format (YYYY-MM-DDTHH:mm:ss)
        login:  string   | null
    }
}[]

---

Get User Info

Returns full information on specified user.

Request:

GET /users/<user>?[nicknames][icon]

Authorization: Bearer <access token> -- needed if anonym access isn't allowed
Accept: application/json

Response:

{
    login:      string
    name:       string   | null
    icon?:      string   | null // Added if <icon> URL option is set ("data:image/png;base64,...")
    nicknames?: string[]        // Added if <nicknames> URL option is set
    isAdmin:    boolean
    isOnline:   boolean

    reg: {
        time:   string          // In ISO 8601 format (YYYY-MM-DDTHH:mm:ss)
        login:  string | null
    }
}

---

Get User Login

Returns specified user login

Request:

GET /users/<user>/login

Authorization: Bearer <access token> -- needed if anonym access isn't allowed
Accept: application/json

Responese:

{
    login: string
}

---

Check If User Is Administrator

Returns boolean value indicating weather is specified user administrator.

Request:

GET /users/<user>/is-admin

Authorization: Bearer <access token> -- needed if anonym access isn't allowed
Accept: application/json

Responese:

{
    isAdmin: boolean
}

---

Check If User Is Online

Returns boolean value indicating weather is specified user online.

Request:

GET /users/<user>/online

Authorization: Bearer <access token> -- needed if anonym access isn't allowed
Accept: application/json

Responese:

{
    isOnline: boolean
}

---

Get User Registration Info

Returns full registration information on specified user.

Request:

GET /users/<user>/reg

Authorization: Bearer <access token> -- needed if anonym access isn't allowed
Accept: application/json

Responese:

{
    time:  string        // In ISO 8601 format (YYYY-MM-DDTHH:mm:ss)
    login: string | null
}

---

Get User Registration Time

Returns user registration time.

Request:

GET /users/<user>/reg/time

Authorization: Bearer <access token> -- needed if anonym access isn't allowed
Accept: application/json

Responese:

{
    time: string // In ISO 8601 format (YYYY-MM-DDTHH:mm:ss)
}

---

Get User Registrar

Returns user registrar or null if user was registered by the system.

Request:

GET /users/<user>/reg/user

Authorization: Bearer <access token> -- needed if anonym access isn't allowed
Accept: application/json

Responese:

{
    login: string | null
}

---

Get User Name

Returns name of specified user.

Request:

GET /users/<user>/name

Authorization: Bearer <access token> -- needed if anonym access isn't allowed
Accept: application/json

Response:

{
    name: string | null
}

---

Get User Icon

Returns icon of specified user.

Request:

GET /users/<user>/icon

Authorization: Bearer <access token> -- needed if anonym access isn't allowed
Accept: application/json

Response:

{
    icon: string | null // "data:image/png;base64,..."
}

---

Get User Nicknames

Returns list of user nicknames.

Request:

GET /users/<user>/nicknames/

Authorization: Bearer <access token> -- needed if anonym access isn't allowed
Accept: application/json

Response:

string[]

---

Get Server Status

Returns server's status.

Request:

GET /server

Authorization: Bearer <access token> -- needed if anonym access isn't allowed
Accept: application/json

Response:

{
    version: {
        name:         string
        protocol:     number
    }

    players: {
        online:       number
        max:          number,
        sample: {
            nickname: string
            login:    string | null
        }[]
    }

    motd: {
        raw:          string
        clean:        string
        html:         string
    }

    address:          string | null
    favicon:          string | null // "data:image/png;base64,..."
}

---

Get Server Version

Returns server's version.

Request:

GET /server/version

Authorization: Bearer <access token> -- needed if anonym access isn't allowed
Accept: application/json

Response:

{
    name:     string
    protocol: number
}

---

Get Server Version Name

Returns server's version name.

Request:

GET /server/version/name

Authorization: Bearer <access token> -- needed if anonym access isn't allowed
Accept: application/json

Response:

{
    name: string
}

---

Get Server Version Protocol

Returns server's version protocol.

Request:

GET /server/version/protocol

Authorization: Bearer <access token> -- needed if anonym access isn't allowed
Accept: application/json

Response:

{
    protocol: number
}

---

Get Server Players

Returns server's players.

Request:

GET /server/players

Authorization: Bearer <access token> -- needed if anonym access isn't allowed
Accept: application/json

Response:

{
    online:       number
    max:          number,
    sample: {
        nickname: string
        login:    string | null
    }[]
}

---

Get Server Players Count

Returns server's online and offline players count.

Request:

GET /server/players/count

Authorization: Bearer <access token> -- needed if anonym access isn't allowed
Accept: application/json

Response:

{
    online: number
    max:    number
}

---

Get Server Online Players

Returns server's online players count.

Request:

GET /server/players/online

Authorization: Bearer <access token> -- needed if anonym access isn't allowed
Accept: application/json

Response:

{
    online: number
}

---

Get Server Max Players

Returns server's maximum number of players.

Request:

GET /server/players/max

Authorization: Bearer <access token> -- needed if anonym access isn't allowed
Accept: application/json

Response:

{
    max: number,
}

---

Get Server Players Sample

Returns server's players sample.

Request:

GET /server/players/sample

Authorization: Bearer <access token> -- needed if anonym access isn't allowed
Accept: application/json

Response:

{
    nickname: string
    login:    string | null
}[]

---

Get Server MOTD

Returns server's Message Of The Day (MOTD).

Request:

GET /server/motd

Authorization: Bearer <access token> -- needed if anonym access isn't allowed
Accept: application/json

Response:

{
    raw:   string
    clean: string
    html:  string
}

---

Get Server Raw MOTD

Returns server's raw Message Of The Day (MOTD).

Request:

GET /server/motd/raw

Authorization: Bearer <access token> -- needed if anonym access isn't allowed
Accept: application/json

Response:

{
    raw: string
}

---

Get Server Clean MOTD

Returns server's clean Message Of The Day (MOTD).

Request:

GET /server/motd/clean

Authorization: Bearer <access token> -- needed if anonym access isn't allowed
Accept: application/json

Response:

{
    clean: string
}

---

Get Server HTML MOTD

Returns server's HTML Message Of The Day (MOTD).

Request:

GET /server/motd/html

Authorization: Bearer <access token> -- needed if anonym access isn't allowed
Accept: application/json

Response:

{
    html: string
}

---

Get Server Address

Returns server's public address.

Request:

GET /server/address

Authorization: Bearer <access token> -- needed if anonym access isn't allowed
Accept: application/json

Response:

{
    address: string | null
}

---

Get Server Favicon

Returns server's favicon.

Request:

GET /server/favicon

Authorization: Bearer <access token> -- needed if anonym access isn't allowed
Accept: application/json

Response:

{
    favicon: string | null // "data:image/png;base64,..."
}

---

Delete All Users

Deletes all users! This method is for administators only.

Request:

DELETE /users

Authorization: Bearer <admin access token>
Accept: application/json

Response:

{
    count: number
}

---

Delete User

Deletes specified user.

If issued with administator's access token user - can be any user's login otherwise can only be a token owener's login.

Request:

DELETE /users/<user>

Authorization: Bearer <access token>
Accept: application/json

---

Delete All User nicknames

Deletes all nicknames of specified user.

If issued with administator's access token user - can be any user's login otherwise can only be a token owener's login.

Request:

DELETE /users/<user>/nicknames

Authorization: Bearer <access token>
Accept: application/json

Response:

{
    count: number
}

---

Delete User Nickname

Deletes specified nickname of given user.

If issued with administator's access token user - can be any user's login otherwise can only be a token owener's login.

Request:

DELETE /users/<user>/nicknames/<nickname>

Authorization: Bearer <access token>
Accept: application/json

Response:

{}

---

Update User

Updates all user fields.

If issued with administator's access token user - can be any user's login otherwise can only be a token owener's login.

Request:

PUT /users/<user>

Authorization: Bearer <access token>
Content-Type: application/json
Accept: application/json

Response:

{
    name?:      string   | null
    icon?:      string   | null // "data:image/png;base64,..."
    nicknames?: string[]
    isAdmin?:   boolean         // Ignored if issuer is not an admin
}

---

Update User Name

Updates specified user name.

If issued with administator's access token user - can be any user's login otherwise can only be a token owener's login.

Request:

PUT /users/<user>/name

Authorization: Bearer <access token>
Content-Type: application/json
Accept: application/json

{
    name: string | null
}

Response:

{}

---

Update User Icon

Updates specified user icon.

If issued with administator's access token user - can be any user's login otherwise can only be a token owener's login.

Request:

PUT /users/<user>/icon

Authorization: Bearer <access token>
Content-Type: application/json
Accept: application/json

{
    icon: string | null // "data:image/png;base64,..."
}

Response:

{}

---

Update User Password

Updates specified user password.

If issued with administator's access token user - can be any user's login otherwise can only be a token owener's login.

Request:

PUT /users/<user>/password

Authorization: Bearer <access token>
Content-Type: application/json
Accept: application/json

{
    password: string
}

Response:

{}

---

Update User Permissions

Changes whether is specified user is administrator or not. This method is for administators only.

Request:

PUT /users/<user>/is-admin

Authorization: Bearer <admin access token>
Content-Type: application/json
Accept: application/json

{
    isAdmin: boolean
}

Response:

{}

---

Update User Nicknames

Updates user nicknames.

If issued with administator's access token user - can be any user's login otherwise can only be a token owener's login.

Request:

PUT /users/<user>/nicknames

Authorization: Bearer <access token>
Content-Type: application/json
Accept: application/json

Response:

string[]

---

Add User Nickname

Adds nickname to the user.

If issued with administator's access token user - can be any user's login otherwise can only be a token owener's login.

Request:

POST /users/<user>/nicknames/<nickname>

Authorization: Bearer <access token>
Accept: application/json

Response:

{}

---

Add User

Adds new user. This method is for administators only.

Request:

POST /users/<user>

Authorization: Bearer <admin access token>
Content-Type: application/json
Accept: application/json

{
    password:   string
    name?:      string   | null
    icon?:      string   | null // "data:image/png;base64,..."
    isAdmin?:   boolean
    nicknames?: string[]
}

Response:

{}