GitHubHelp

Tom-The-Geek/nucleoid-persistence-backend

WIP MongoDB based backend for storing persistent data

★ 1Forks 0RustGitHub ↗Compare

README

ARCHIVED: Development of this has moved to the nucleoid-backend repo here. See this PR

nucleoid-persistence-backend (name WIP)

HTTP-based REST API for per-player, per-minigame key-value storage based on MongoDB.

What can be stored?

Currently, the API can store:

  • player uuid -> username
  • per-player, per-minigame statistic storage.
    • It currently supports storing a total or a rolling average integer value (returns a float for calculated average)

Authentication

In order to allow this API to be exposed for public read access, certain endpoints require an authentication token in order to make successful requests. Authentication tokens are stored in the config.json file, and on first run, a random 64 character string is generated as a default token. Tokens can simply be added or removed from the server_tokens option in order to create new tokens or invalidate old ones.

Authentication tokens should be passed in the Authorization HTTP header on every request to an authenticated endpoint. Endpoints that require authentication are marked below with a (*). If a request is missing the header, it will receive a 400 Bad request, and if it has an invalid token in the Authorization header, it will receive a 401 Unauthorized error.

Statistic storage

The player statistic storage allows the following types of statistic to be stored:

  • Raw value (stored as an int)
  • Rolling average (stored as a total and count)

REST API

GET /player/{uuid}

Path parameters

Name Type Description
uuid UUID The player UUID to look up

Response body

Name Type Description
uuid UUID The UUID of the player
username String? The player's username, if known, will be missing if not

PUT /player/{uuid} (*)

Path parameters

Name Type Description
uuid UUID The player UUID to update

Request body

Name Type Description
username String The player's username, to be updated in the database

Response

This endpoint returns 204 no content on a successful request

GET /player/{uuid}/stats/{namespace}

Path parameters

Name Type Description
uuid UUID The player UUID to lookup stats for
namespace String The namespace of stats to lookup, typically the name/mod id of the minigame; eg. bed-wars

Response body

The response body is a Map<String, float> containing the values of all known statistics for the player. If the statistic is a raw value, it will simply be returned, and if it is a rolling average, then the calculated average will be returned.

POST /stats/upload (*)

Should be called by the minigame server after a game has finished, to upload the stats for players in that game.

Request body

Name Type Description
server_name String Name of the server uploading the bundle; eg. play (currently unused by the backend)
namespace String The namespace of the game; eg bed-wars
stats Object An object containing all stats for this game, including those for players and global stats. See the example for the layout Note: statistic ids cannot contain '.'s.

Stat types

Name Value type
int_total int
int_rolling_average int
float_total float or double
float_rolling_average float or double

Example payload

{
  "server_name": "play",
  "namespace": "example-game",
  "stats": {
    "players": {
      "07e92b46838640678f728ab96e606fb7": {
        "example-1": {
          "type": "int_total",
          "value": 10
        },
        "example-2": {
          "type": "float_rolling_average",
          "value": 15.2
        }
      }
    },
    "global": {
      "example-3": {
        "type": "int_rollling_average",
        "value": 42
      },
      "example-4": {
        "type": "float_total",
        "value": 4.2
      }
    }
  }
}

Contributors

Tom-The-Geek

Issues