Difference between revisions of "Server Status (API)"

Revision as of 23:23, 13 June 2012

Implementation Status: Implemented
URI: https://api.kag2d.com/server/ip/IPADDRESS/port/PORT/status
HTTP Verbs Supported: GET
Response Type: JSON dictionary
HTTP Auth Required: No

IPADDRESS is the IPv4 or IPv6 address of the server, PORT is the game port.

Current structure:

• (int) DNcycle: Whether or not the server has the day/night cycle enabled. 0/1 represent boolean. Should always be present.
• (int) DNState: The current daylight/night state. Values are 0-255. Should always be present.
• (int) currentPlayers: The current number of players in the server. Should always be present.
• (string) description: The description of the server (e.g. sv_description). Currently does not exceed 144 characters but may be more in the future. Should always be present.
• (string) firstSeen: ISO 9075 date format indicating when the API first recorded this server. See Server Addresses (API). Note: This is likely soon going to be replaced with a HTTP header. Not sure which one yet.
• (string) gameMode: string representing the game mode. See gameMode (API). Should always be present.
• (int) gameState: 0/1 representing boolean. 0 means the game is in warmup/build time, 1 means the game is running. Should always be present.
• (int) gold: 0/1 representing boolean. 0 is not gold, 1 is gold only. Should always be present.
• (string) lastUpdate: when the API last updated this server. Note: This is very soon going to be replaced with a HTTP Last-Modified header, so please check for that and use it instead if it is present.
• (int) mapH: The height of the current map, in tiles. Should always be present.
• (int) mapW: The width of the current map, in tiles. If this and mapH are both zero, it likely means a map is not loaded/generated yet. Should always be present.
• (int) maxPlayers: The player limit currently set on this server. Should always be present.
• (int) password: 0/1 representing boolean. 0 is no password, 1 means a password is required to enter the server. Should always be present.
• (array) playerList: a list of players in the server as of the lastUpdate/Last-Modified time. Note: This is going to be changing to an object type as players have extra data associated with them. Should always be present.
• (string) serverIPv6Address: The IPv6 address of the server. Not always present as most servers are IPv4-only. See IPv6 and Server Addresses (API)
• (string) serveriPv4Address: The IPv4 address of the server. Not always present (there will eventually be IPv6-only servers). See Server Addresses (API)
• (string) serverName: The name of the server.
• (int) serverPort: The port of the server.

Additional keys will be added in the future, do not write code which will fail if additional keys are present. Do not write code which will break/crash if one of the above attributes is missing.

Examples

https://api.kag2d.com/server/ip/2400:c400::113:212:96:217/port/50301/status

{
 "serverStatus": {
   "DNCycle": 0, 
   "DNState": 0, 
   "currentPlayers": 0, 
   "description": "Managed by lavalord", 
   "firstSeen": "2012-06-11 09:08:23", 
   "gameMode": "Capture the Flag!", 
   "gameState": 1, 
   "gold": 0, 
   "lastUpdate": "2012-06-13 18:05:55", 
   "mapH": 150, 
   "mapW": 250, 
   "maxPlayers": 24, 
   "password": 0, 
   "playerList": [], 
   "serverIPv4Address": "113.212.96.217", 
   "serverIPv6Address": "2400:c400::113:212:96:217", 
   "serverName": "Australian unofficial Server", 
   "serverPort": 50301
 }
}

https://api.kag2d.com/server/ip/67.23.118.185/port/50314/status

{
 "serverStatus": {
   "DNCycle": 1, 
   "DNState": 0, 
   "currentPlayers": 0, 
   "description": "Default config, hosted in the eastern US (Reston, VA)", 
   "firstSeen": "2012-06-07 08:04:40", 
   "gameMode": "Capture the Flag!", 
   "gameState": 1, 
   "gold": 1, 
   "lastUpdate": "2012-06-13 18:22:55", 
   "mapH": 128, 
   "mapW": 200, 
   "maxPlayers": 32, 
   "password": 0, 
   "playerList": [], 
   "serverIPv4Address": "67.23.118.185", 
   "serverIPv6Address": "2607:fd50:1:91b0::c414", 
   "serverName": "U13 USEast 32 slot FullCTF Gold", 
   "serverPort": 50314
 }
}