Players¶

Players are an integral entity within the API. Every resource that requires authentication (see Authentication) requires player credentials to make use of them, and several resources have more direct links to players (e.g. devgroups consist of lists of players).

Of particular note is the player token resources, which are useful for verifying that a player is who they say they are. A player client can request a new token and pass it to a service that needs to verify their identity (such as a game server), then said service can validate that token independently, confirming the player’s identity.

A game client can also use the myinfo resource to authenticate a player, as the API will only return a 200 status code if the provided credentials are correct.

There is currently no way to create a new player via the API, you have to register at http://kag2d.com/ in order to do that.

GET /player/(username)/info¶

Player public info resource.

Example request:

GET /player/shadlington/info HTTP/1.1
Host: api.kag2d.com
Accept: application/json

Example response:

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

{
  "playerInfo": {
    "active": true,
    "banExpiration": null,
    "banReason": null,
    "banned": false,
    "gold": true,
    "gold_storm": true,
    "gold_trenchrun": true,
    "regUnixTime": 1386522342,
    "registered": "2013-12-08 17:05:42",
    "role": 1,
    "username": "Shadlington"
  }
}

Response JSON fields:
Parameters:	username – player’s kag username
Status Codes:	200 – when player exists 404 – when player doesn’t exist
	username The canonical representation of the username (cased) active The player account activation status role Integer representation of player role (0-6) gold Has the player purchased kag? gold_storm Has the player purchased storm? gold_trenchrun Has the player purchased trenchrun? registered Registration time, format: YYYY-MM-DD hh:mm:ss regUnixTime Registration in seconds since epoch (unix time) banned Is the player banned? i.e. any ban flags active at all banReason Reason for the ban. null if banned is false banExpiration When the ban expires. null if banned is false

GET /player/(username)/myinfo¶

Player private info resource. Uses HTTP basic auth - the username in the authorization header must match the username in the URL.

Example requests:

GET /player/shadlington/myinfo HTTP/1.1
Host: api.kag2d.com
Accept: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Example response:

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

{
  "playerInfoPrivate": {
    "active": true,
    "banExpiration": null,
    "banReason": null,
    "banned": false,
    "gold": true,
    "gold_storm": true,
    "gold_trenchrun": true,
    "receiveEmails": true,
    "regUnixTime": 1386522342,
    "registered": "2013-12-08 17:05:42",
    "role": 1,
    "termsAccepted": true,
    "username": "Shadlington"
  }
}

Substatus 40301:
Parameters:	username – player’s kag username
Status Codes:	200 – when player exists and authorization is valid 401 – when the authorization headers are missing/invalid (which also applies if the username in the header doesn’t exist). 403 – when the auth header username doesn’t match the username in the URL, or the player is inactive.
	when the auth is correct but the player is inactive.
Response JSON fields:
	username The canonical representation of the username (cased) active The player account activation status role Integer representation of player role (0-6) gold Has the player purchased kag? gold_storm Has the player purchased storm? gold_trenchrun Has the player purchased trenchrun? registered Registration time, format: YYYY-MM-DD hh:mm:ss regUnixTime Registration in seconds since epoch (unix time) banned Is the player banned? i.e. any ban flags active at all banReason Reason for the ban. null if banned is false banExpiration When the ban expires. null if banned is false receiveEmails Does the player receive site emails termsAccepted Has the player accepted the terms?

GET /player/(username)/foruminfo¶

Player private info resource, used for authentication on the forums. Uses HTTP basic auth - the username in the authorization header must match the username in the URL.

Example requests:

GET /player/shadlington/foruminfo HTTP/1.1
Host: api.kag2d.com
Accept: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Example response:

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

{
  "playerInfoForum": {
    "active": true,
    "banExpiration": null,
    "banReason": null,
    "banned": false,
    "email": "notarealemail@bluh.com",
    "gold": true,
    "gold_storm": true,
    "gold_trenchrun": true,
    "role": 1,
    "userID": 9001,
    "username": "Shadlington"
  }
}

Substatus 40301:
Parameters:	username – player’s kag username
Status Codes:	200 – when player exists and authorization is valid 401 – when the authorization headers are missing/invalid (which also applies if the username in the header doesn’t exist). 403 – when the auth header username doesn’t match the username in the URL, or the player is inactive.
	when the auth is correct but the player is inactive.
Response JSON fields:
	username The canonical representation of the username (cased) active The player account activation status role Integer representation of player role (0-6) gold Has the player purchased kag? gold_storm Has the player purchased storm? gold_trenchrun Has the player purchased trenchrun? emailAddress The player’s email address userID The player’s user ID banned Is the player banned? i.e. any ban flags active at all banReason Reason for the ban. null if banned is false banExpiration When the ban expires. null if banned is false

GET /player/(username)/status¶

Player status resource.

Example request:

GET /player/shadlington/status HTTP/1.1
Host: api.kag2d.com
Accept: application/json

Example response:

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

{
  "playerStatus": {
    "action": 2,
    "lastUpdate": "2013-12-08 17:05:49",
    "server": {
      "IPv4Address": "83.6.192.140",
      "IPv6Address": null,
      "port": 50301
    }
  }
}

Response JSON fields:
Parameters:	username – player’s kag username
Status Codes:	200 – when player exists 404 – when player doesn’t exist
	playerStatus Contains the following fields: action Type of update last made. 2 is playing on server. lastUpdate The time the last update was made server The IP address and port of the server the player was last on, if they were on a server (action 2)

GET /player/(username)/banflags¶

Player ban flags resource.

Example request:

GET /player/shadlington/banflags HTTP/1.1
Host: api.kag2d.com
Accept: application/json

Example response:

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

{
  "playerBanFlags": {
    "all": [
      "abuser",
      "griefer"
    ],
    "current": [
      "abuser"
    ]
  }
}

Response JSON fields:
Parameters:	username – player’s kag username
Status Codes:	200 – when player exists 404 – when player or status doesn’t exist
	current List of ban flags that are currently active for this player all List of all ban flags (ever) for this player

GET /player/(username)¶

Player status resource.

Example request:

GET /player/shadlington/status HTTP/1.1
Host: api.kag2d.com
Accept: application/json

Example response:

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

{
  "playerBanFlags": {
    "all": [
      "abuser",
      "griefer"
    ],
    "current": [
      "abuser"
    ]
  },
  "playerInfo": {
    "active": true,
    "banExpiration": "2013-12-09 06:59:09",
    "banReason": "Some reason or other",
    "banned": true,
    "gold": true,
    "regUnixTime": 1386522342,
    "registered": "2013-12-08 17:05:42",
    "role": 1,
    "username": "Shadlington"
  },
  "playerStatus": {
    "action": 2,
    "lastUpdate": "2013-12-08 17:05:49",
    "server": {
      "IPv4Address": "83.6.192.140",
      "IPv6Address": null,
      "port": 50301
    }
  }
}

Response JSON fields:
Parameters:	username – player’s kag username
Status Codes:	200 – when player exists 404 – when player doesn’t exist
	playerBanflags Same as in /player/(username)/banflags playerInfo Same as in /player/(username)/info playerStatus Same as in /player/(username)/status

GET /player/(username)/token/new¶

Player token generation resource. If the user provided in the URL is valid, generates a token for them. Tokens expire after a minute or when they are used, whichever comes first.

Example request:

GET /player/shadlington/token/new HTTP/1.1
Host: api.kag2d.com
Accept: application/json

Example response:

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

{
    "playerToken": "sometokenstring",
}

Substatus 40301:
Parameters:	username – player’s kag username
Status Codes:	200 – when token is correctly generated for this player 401 – when the authorization headers are missing/invalid 403 – when the auth header username doesn’t match the username in the URL, or the player is inactive.
	when the auth is correct but the player is inactive.
Response JSON fields:
	playerToken the string identifying the newly generated token

GET /player/(username)/token/(token)¶

Player token verification resource. Simply checks if the token provided in the URL is valid for this user.

Example request:

GET /player/shadlington/token/sometokenstring HTTP/1.1
Host: api.kag2d.com
Accept: application/json

Example responses:

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

{
  "banned": false,
  "playerTokenStatus": false,
  "statusMessage": "Token not found"
}

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

{
  "banned": false,
  "playerTokenStatus": true,
  "statusMessage": "Token found"
}

Response JSON fields:
Parameters:	username – player’s kag username token – token identifying string
Status Codes:	200 – when token is valid for this player 404 – when token is not valid (for this player or otherwise)
	playerTokenStatus true/false - the token verification status banned Is the player banned? i.e. any ban flags active at all statusMessage Additional human-readable message about token

GET /player/(username)/avatar/(size)¶

Player avatar resource. Requests can either be made to /player/<username>/avatar or /player/<username>/avatar/<size> (where size is s, m or l). In either case the urls of the player avatars are provided - when a size is given, only the url for that size is returned, otherwise all sizes are returned.

Example requests:

GET /player/shadlington/avatar HTTP/1.1
Host: api.kag2d.com
Accept: application/json

GET /player/shadlington/avatar/s HTTP/1.1
Host: api.kag2d.com
Accept: application/json

Example responses:

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

{
  "large": "https://forum.thd.vg/data/avatars/l/0/10.jpg",
  "medium": "https://forum.thd.vg/data/avatars/m/0/10.jpg",
  "small": "https://forum.thd.vg/data/avatars/s/0/10.jpg"
}

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

{
    "small": "https://forum.thd.vg/data/avatars/s/0/10.jpg"
}

Response JSON fields:
Parameters:	username – player’s kag username
Status Codes:	200 – when player exists and they have an avatar 404 – when player doesn’t exist or they have no avatar
	small URL of small version of player avatar medium URL of medium version of player avatar large URL of large version of player avatar

PUT /player/(username)/terms/status¶

Player term status update resource.

Example request:

PUT /player/shadlington/terms/status HTTP/1.1
Host: api.kag2d.com
Content-Type: application/json

{
    "termsStatus":
    {
        "termsVersion": 999,
        "termsHash": somehash,
        "acceptance": 1
    }
}

Example response:

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

{}

Substatus 40301:
Parameters:	username – player’s kag username
Status Codes:	200 – when player terms status is correctly updated 400 – when the request is not correctly formatted as JSON 401 – when the authorization headers are missing/invalid 403 – when the auth header username doesn’t match the username in the URL, or the player is inactive.
	when the auth is correct but the player is inactive.
Request JSON fields:
	termsVersion Game version the terms were accepted in termsHash Hash of the terms acceptance 1/0 (True/False) of terms acceptance

PUT /player/(username)/receiveemails/status¶

Player receive emails status update resource.

Example request:

PUT /player/shadlington/receiveemails/status HTTP/1.1
Host: api.kag2d.com
Content-Type: application/json

{
    "receiveEmails":
    {
        "status": 1
    }
}

Example response:

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

{}

Substatus 40301:
Parameters:	username – player’s kag username
Status Codes:	200 – when player receive emails status is correctly updated 400 – when the request is not correctly formatted as JSON 401 – when the authorization headers are missing/invalid 403 – when the auth header username doesn’t match the username in the URL, or the player is inactive.
	when the auth is correct but the player is inactive.
Request JSON fields:
	status 1/0 (True/False) of receive emails status

Navigation

Players¶

Related Topics

Quick search