Storage

Introduction

ValenceNetwork Storage Daemon

The storage management daemon that handles server creation and it's data for the Valence Network. Works hand in hand with 4302073819

This documentation covers all (current) API endpoints that can be called (public and private). Some key points first:

  • Most endpoints are private (need authentication)
  • Please respect the request type. i.e. a POST to a GET endpoint will error
  • Versioning is required on all requests. i.e. /127.0.0.1/v1/server
  • Arguments can be provided as query string if GET or body json for all other methods

Authentication

API keys are issued manually and automatically in different circumstances. The different authentication levels are as follows:

  • admin - Granted to systems administrators with global access to all endpoints and functions
  • manager - Granted to network manager processes. See /github.com/ValenceNetwork/Network
  • server - Granted to game server instances to update status and perform S3 operations
  • user - Granted to end users requiring informative data pertaining to a server (i.e. one they own)

Authentication to endpoints is easy and very straightforward. All requests that need to be authenticated should include a X-Api-Key header with your api key.

curl -X GET -H 'X-Api-Key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' '127.0.0.0/v1/server'

Responses

All endpoints respond with a uniform response to ensure that processing is easy (including exceptions). Every request will also return a relevant HTTP status code. All successful requests will return an HTTP 200 range response code, and errors will return relevent HTTP 400 or 500 range codes. More details for all requests will be provided in the response json.

Format of all responses:

{
    / Boolean, represents the status of the request
    "success": false,
    / Object representing finer details of the original request
    "details": {
        "http_code": 418
        / A list of information passed in the request
        "provided_data": [
            "dark roast",
            "cream",
            "two sugars"
        ],
        / Epoch timestamp in seconds of when the response was sent
        "timestamp": 123456789,
        / Either null if successful, or an object containing details of an exception
        "error": {
            / The descriptor of the HTTP code
            "description": "I'm a teapot",
            / Actual details causing the exception
            "additional_details": "The requested resource is a teapot and cannot brew coffee"
        },
        / Returns non-null when a server uuid4 id was provided
        "provided_id": null,
    }
}

Example response of files/download:

{
    "success": true,
    "endpoint_response": {
        "files": [
            {
                "updated": true,
                "id": "jars/server.jar",
                "url": "/abc.example.com/bucket/jars/server.jar",
                "type": "SERVER"
            },
            {
                "updated": true,
                "id": "jars/proxy.jar",
                "url": "/abc.example.com/bucket/jars/proxy.jar",
                "type": "PROXY"
            },
            {
                "id": "jars/plugins/test.jar",
                "updated": false,
                "type": "PLUGIN"
            },
            {
                "updated": true,
                "id": "jars/plugins/protocol-support.jar",
                "url": "/abc.example.com/bucket/jars/plugins/protocol-support.jar",
                "type": "PLUGIN"
            }
        ]
    },
    "details": {
        "provided_data": [
            "server.jar",
            "proxy.jar",
            "reflex.jar",
            "protocol-support.jar"
        ],
        "timestamp": 123456789,
        "error": null,
        "http_code": 200
    }
}

Example error response from server/delete:

{
    "success": false,
    "details": {
        "http_code": 404,
        "error": {
            "description": "Resource not found",
            "additional_details": "Requested server to be deleted does not exist or is not running"
        },
        "provided_id": "40ac54c0-56a0-4b61-b42d-ba44634f5fdb",
        "timestamp": 123456789
    },
    "endpoint_response": null
}

Endpoints

GET /server/{uuid}

Retrieves information about a server.

Response types:

  • 200 - Success
  • 403 - Access forbidden; the requester does not have the api privilege to request this endpoint and was authenticated properly
  • 404 - Requested server does not exist
  • 500 - A server error

POST /server/create

Start's a players gameserver or creates a new one if it does not exist. Will eventually move to /server/create/{uuid}.

Args
{
    "uuid": "65667412-b232-434c-9a31-996e8fb0672a"
}
Response types
  • 201 - Success
  • 403 - Access forbidden; the requester does not have the api privilege to request this endpoint and was authenticated properly
  • 409 - Conflict. Returned when a server is already started or starting
  • 500 - A server error

DELETE /server/delete

Saves the world and destroys a provided game server instance. Will eventually move to /server/delete/{uuid}.

Args
{
    "uuid": "65667412-b232-434c-9a31-996e8fb0672a"
}
Response types
  • 200 - Success
  • 403 - Access forbidden; the requester does not have the api privilege to request this endpoint and was authenticated properly
  • 404 - Requested server does not exist
  • 500 - A server error

POST /server/update

Internally used as a callback on node startup with information about the server.

Args
{
    "uuid": "65667412-b232-434c-9a31-996e8fb0672a",
    "ip": "127.0.0.1",
    "droplet_id": 12345
}
Response types
  • 200 - Success
  • 400 - Invalid data types provided
  • 403 - Access forbidden; the requester does not have the api privilege to request this endpoint and was authenticated properly
  • 500 - A server error

POST /files/download

Compares a list of provided files against the hash of the ones in the space, and if different returns a download link for ones needing an update (can also force a download with "forceUrl": true). If an md5 hash is not provided, then it will default to null.

Args
{
    "files": [
        {   / A string dictating the type of file requested. One of: "SERVER", "PROXY", "PLUGIN", "DATA". Always required
            "type": "SERVER"
        },
        {
            "type": "PROXY",
            / MD5 hash of client side file. Compared with S3 bucket to check for a match if provided
            "hash": "3487ghbfudyjnf789349fjn39f942nhbvs7fc"
        },
        {
            / Used when a specific name is required with the type to identify which file
            "id": "worldedit",
            "type": "PLUGIN",
            / Forces a download link to be generated. Works even when provided hash matches that of S3
            "forceUrl": true
        },
        {   / In the case of server data, the server's uuid4 is required
            "id": "c9343d0e-5e2a-4db4-87ef-48bce013c87e",
            "type": "DATA"
        }
    ]
}