Servers¶

Servers are game-specific entities, so all resources in this section are game-specific themselves (see: Game-specific URL prefixes).

[TODO: Flesh this section out]

GET /game/(gamedev)/(game)/server/(ip)/(int: port)/status¶

Server status retrieval resource. Note that the game specified by the prefix must match the game that the server being requested is running.

Example request:

GET /game/thd/kag/server/192.0.2.3/50301/status HTTP/1.1
Host: api.kag2d.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "serverStatus": {
    "DNCycle": true,
    "DNState": 0,
    "IPv4Address": "192.0.2.3",
    "IPv6Address": null,
    "build": 999,
    "connectable": true,
    "currentPlayers": 2,
    "description": "Some description of the server",
    "firstSeen": "2013-12-08 19:24:55",
    "gameMode": "Sandbox",
    "gameState": 1,
    "gameID": 1,
    "gold": true,
    "lastUpdate": "2013-12-08 19:24:55",
    "mapH": 150,
    "mapW": 150,
    "maxPlayers": 10,
    "maxSpectatorPlayers": 2,
    "modsVerified": false,
    "name": "Some server name",
    "password": true,
    "playerList": [
      "Shadlington",
      "Troll"
    ],
    "playerPercentage": 0.2,
    "port": 50301,
    "preferAF": 4,
    "reservedPlayers": 2,
    "spectatorPlayers": 0,
    "usingMods": false
  }
}

Response JSON fields:
Parameters:	ip – server’s ip address (can be IPv4 or IPv6) port – server’s port number
Status Codes:	200 – when server exists 400 – when the IP address or port is not valid 404 – when server doesn’t exist
	DNCycle is the server running a day night cycle? DNState is the server currently in day or night? IPv4Address Server IPv4 address. Null if no IPv4 address IPv6Address Server IPv6 address. Null if no IPv6 address build Build number that the server is running connectable Is the server connectable? currentPlayers The number of players currently on the server description The server’s description firstSeen Timestamp of the first server status update gameMode The game mode the server is currently running gameState Server game state flag gameID The ID of the game the server is running gold Is the server gold-only? lastUpdate Timestamp of the last server status update mapH The server map height mapW The server map width maxPlayers The max players allowed on the server maxSpectatorPlayers The max spectator players modsVerified If all mods the server is using are verified name The server name password Is the server passworded? playerList A list of the players currently on the server playerPercentage The percentage that the server is filled port The server port preferAF Type of IP protocol preferred by the server reservedPlayers The number of player slots reserved spectatorPlayers The current number of spectator players usingMods Is the server using any mods?

PUT /game/(gamedev)/(game)/server/(ip)/(int: port)/status¶

Server status update resource. Note that the server will be updated as running the game that is specified in the prefix.

Example request:

PUT /game/thd/kag/server/192.0.2.3/50301/status HTTP/1.1
Host: api.kag2d.com
Content-Type: application/json

{
  "serverStatus": {
    "DNCycle": true,
    "DNState": 0,
    "IPv4Address": "192.0.2.3",
    "IPv6Address": null,
    "build": 999,
    "currentPlayers": 2,
    "description": "Some description of the server",
    "gameMode": "Sandbox",
    "gameState": 1,
    "gold": true,
    "mapH": 150,
    "mapW": 150,
    "maxPlayers": 10,
    "maxSpectatorPlayers": 2,
    "modsVerified": false,
    "name": "Some server name",
    "password": true,
    "playerList": {
      "Shadlington": "placeholder",
      "Troll": "placeholder"
    },
    "port": 50301,
    "preferAF": 4,
    "reservedPlayers": 2,
    "spectatorPlayers": 0,
    "usingMods": false
  }
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{}

Substatus 20001:
Parameters:	ip – server’s ip address (can be IPv4 or IPv6) port – server’s port number
Status Codes:	200 – when server status update is successful 400 – when there is anything invalid about the request body 401 – when the authorization headers are missing/invalid 403 – when you perform the update from an IP address that is not authorised to update the server.
	you authorised another IP but you still need to call from it to be able to use it to identify the server (in the URL). The IP you authorised/need to call from is in the ‘callbackSource’ key of the response body.
Substatus 20002:
	the update was successful but the server is not connectable for some reason, and won’t appear in the in-game client server list.
Substatus 40303:
	the IP you called from isn’t authorised for the server you are updating. You need to update the server from an authorised IP (the one to use will be in the ‘callbackSource’ key of the response body), specifying the IP to authorise in the request body.
Request JSON fields:
	serverStatus Same as for the server status GET resource, with the exception of the playerList, which is an Object instead of an Array (where the players are the keys and all the values are “placeholder”). Also, you don’t include the keys connectable, playerPercentage, firstSeen or lastUpdate.

GET /game/(gamedev)/(game)/server/(ip)/(int: port)/minimap¶

Server minimap retrieval resource. When successful (i.e. 200) the response body is a PNG file. Note that the game specified by the prefix must match the game that the server being requested is running.

Example request:

GET /game/thd/kag/server/192.0.2.3/50301/minimap HTTP/1.1
Host: api.kag2d.com
Accept: image/png

Example response:

HTTP/1.1 200 OK
Content-Type: image/png

[Some PNG file data]

Parameters:	ip – server’s ip address (can be IPv4 or IPv6) port – server’s port number
Status Codes:	200 – when server & server minimap exist 400 – when the IP address or port is not valid 404 – when server or minimap doesn’t exist

PUT /game/(gamedev)/(game)/server/(ip)/(int: port)/minimap¶

Server minimap update resource. Note that the game specified by the prefix must match the game that the server (for which the minimap is being updated) is running.

Example request:

PUT /game/thd/kag/server/192.0.2.3/50301/minimap HTTP/1.1
Host: api.kag2d.com
Content-Type: image/png

Example response:

HTTP/1.1 200 OK
Content-Type: image/png

{
  "statusMessage": "2801 byte minimap successfully saved"
}

Parameters:

ip – server’s ip address (can be IPv4 or IPv6)
port – server’s port number

Status Codes:

200 – when server minimap update is successful
400 – when the IP address or port is not valid
401 – when the authorization headers are missing/invalid
403 – when you perform the update from an IP address that is not authorised to update the server.
404 – when server you’re trying to update doesn’t exist yet
415 – when the data sent isn’t a valid PNG file

GET /game/(gamedev)/(game)/servers¶

Server list resource. This is a list resource and therefore the notes in the introduction concerning list resources are relevant here: List type resources. Note that the server list will be filtered down to servers running the game specified by the prefix.

Special filter: If you specify a filter with the field ‘current’ and a value of either true or false (the operator is always eq) then the server list will be filtered to servers that have been updated within the last 32 seconds - i.e. currently active servers.

Example URL:

/game/thd/kag/servers?filters=[{“field”: “build”, “op”: “eq”, “value”: 590}]&limit=5&start=10

Example request:

GET /game/thd/kag/servers HTTP/1.1
Host: api.kag2d.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "serverList": [
    {
      "DNCycle": true,
      "DNState": 0,
      "IPv4Address": "192.0.2.3",
      "IPv6Address": null,
      "build": 999,
      "connectable": true,
      "currentPlayers": 2,
      "description": "Some description of the server",
      "firstSeen": "2013-12-08 19:24:55",
      "gameMode": "Sandbox",
      "gameState": 1,
      "gameID": 1,
      "gold": true,
      "lastUpdate": "2013-12-08 19:24:55",
      "mapH": 150,
      "mapW": 150,
      "maxPlayers": 10,
      "maxSpectatorPlayers": 2,
      "modsVerified": false
      "name": "Some server name",
      "password": true,
      "playerList": [
        "Shadlington",
        "Troll"
      ],
      "playerPercentage": 0.2,
      "port": 50301,
      "preferAF": 4,
      "reservedPlayers": 2,
      "spectatorPlayers": 0,
      "usingMods": false
    },
    {
      anotherserver (same format as above)
    }
  ]
}

Query Parameters:
	start (variable) – which server list result to start from limit (variable) – how many servers to retrieve from the list filters (variable) – The filters to apply to the server list
Status Codes:	200 – all good 400 – when the filters/limit/start are invalid in any way
Response JSON fields:
	serverList List of server statuses that match the filter criteria provided. Contents same as the server status resource.

GET /game/(gamedev)/(game)/servers/filterinfo¶

Server list filter info resource This is a list filterinfo resource and therefore the notes in the introduction concerning list resources are relevant here: List type resources. Note that the game prefix currently doesn’t do anything for this resource (though will eventually cause the resource to return only the filters relevant to the specified game).

Example request:

GET /game/thd/kag/servers/filterinfo HTTP/1.1
Host: api.kag2d.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "serverListFilterFields": [
    {
      "name": "gold",
      "type": "int"
    },
    {
      "name": "usingMods",
      "type": "int"
    },
    {
      "name": "modsVerified",
      "type": "int"
    },
    {
      "name": "mapH",
      "type": "int"
    },
    {
      "name": "spectatorPlayers",
      "type": "int"
    },
    {
      "name": "maxPlayers",
      "type": "int"
    },
    {
      "name": "preferAF",
      "type": "int"
    },
    {
      "name": "gameState",
      "type": "int"
    },
    {
      "name": "mapW",
      "type": "int"
    },
    {
      "name": "port",
      "type": "int"
    },
    {
      "name": "connectable",
      "type": "int"
    },
    {
      "alias": "name",
      "name": "serverName",
      "type": "string"
    },
    {
      "name": "currentPlayers",
      "type": "int"
    },
    {
      "name": "DNCycle",
      "type": "int"
    },
    {
      "name": "build",
      "type": "int"
    },
    {
      "name": "playerPercentage",
      "type": "float"
    },
    {
      "name": "lastUpdate",
      "type": "datetime"
    },
    {
      "name": "gameMode",
      "type": "string"
    },
    {
      "name": "description",
      "type": "string"
    },
    {
      "name": "sid",
      "type": "string"
    },
    {
      "name": "maxSpectatorPlayers",
      "type": "int"
    },
    {
      "name": "reservedPlayers",
      "type": "int"
    },
    {
      "name": "password",
      "type": "int"
    },
    {
      "name": "firstSeen",
      "type": "datetime"
    },
    {
      "alias": "IPv4Address",
      "name": "IPv4",
      "type": "string"
    },
    {
      "alias": "IPv6Address",
      "name": "IPv6",
      "type": "string"
    },
    {
      "name": "DNState",
      "type": "int"
    },
    {
      "info": "If true, filter to active servers",
      "name": "current",
      "ops": "eq",
      "type": "bool"
    }
  ],
  "serverListFilterOperators": [
    {
      "meaning": ">",
      "name": "gt"
    },
    {
      "meaning": "<",
      "name": "lt"
    },
    {
      "meaning": "!=",
      "name": "ne"
    },
    {
      "meaning": ">=",
      "name": "ge"
    },
    {
      "meaning": "<=",
      "name": "le"
    },
    {
      "meaning": "=",
      "name": "eq"
    }
  ]
}

Response JSON fields:
Status Codes:	200 – always (ideally)
	serverListFilterFields The fields that you can filter the server list by, with their types serverListFilterOperators The operators that you can filter the server list with, with their meanings (underlying operator)

Navigation

Servers¶

Related Topics

Quick search