API Endpoints

API-Endpoints

How does the API work? Where is it?

---

Overview

First, some general things to note about the API. Whenever you request data or demand for an action to be taken, the API will respond in the following format:

{
    ["success": true,]          // only set, if the requested action was successful
    ...                         // remaining attributes depend on the request
}

Therefore, one can easily tell, if a request was carried out successfully by taking a look at whether or not the success-attribute is truthy.

Error handling

Whenever a request fails, due to whatever reasons, the API will always respond in the following way:

1. Set the HTTP status code accordingly
2. In the responding JSON data, include the msg-attribute which provides very basic information as to what went wrong (possibly just the error code itself).

{
    "msg": "[error-message]"    // message is dependent on the request and error
}

---

/api/map

GET ANY USER

... is the simplest way to retrieve map data from the API. This will always return the current "main" map, as specified by res/maps/conf.json (see Files-Documentation).

If successful, the response will have the following format:

{
    "success": true,        // indicates a successful request
    "map": {...}            // the actual map data
}

The map data, of course, will be in the regular Map format.

/api/map/:m_name

GET LOGGED-IN USERS

... is the only way to retrieve maps other than the current_map. If the map, specified by its name, stored in m_name, exists and no internal server error occurrs, it will be returned via the response in the same format that /api/map uses.

PUT ADMIN-ONLY

... will, instead of returning a map, create a new map or override an older version of a map.

The request's body has to be in the following format:

{
    "map": map              // the map to-be-stored 
}

For information on the map format itself, see Map-Format

/api/version/:m_name

GET LOGGED-IN USERS

... can be used to get the target map's (m_name) version. The response will look like this:

{
    "success": true,        // indicates a successful request
    "version": "[version]"  // specifies the map's version
}

/api/maps

GET LOGGED-IN USERS

... is used to get a list of all maps available to logged-in users. The response will be of the following format:

{
    "success": true,        // indicates a successful request
    "maps": [               // array containing all maps
        {
            "name": "[m_name]",             // the map-file's name
            "timestamp": "[timestamp]"      // last-edited timestamp - from OS
        },
        ...                                 // of variable length
    ]
}

/api/login

POST ANY USER

... is responsible for authenticating users and starting sessions. All of the above will be done in the following steps:

Whereas the request body has to be in the following format:

{
    "uname": "[username]",  // the username
    "pwd": "[password]",    // the password
}