API

This is a design evaluation document (DRAFT). It might change.

Notes: These are all public, readonly resources at the moment. There are no API keys or encryption.
There probably won't be a need for API versioning at this scale, but it could be added via GET parameters later on.
The Base URL for all the following requests is http://stats.xonotic.org/ (or your local installation).

Formats: The only format currently considered is JSON. It needs to be appended to the resource URL as .json. Omitting a specific format identifier will return the standard HTML resource.
Example: http://stats.xonotic.org/player/1.json

RESTful API Documentation

Player

Player information relating to a single player.

Resource	Parameters	Description
GET /player/:id	id - a system internal player number (required) crypto_id - a players public fingerprint (alternative)	A resource is identified either by a player-id or a crypto-id.
GET /player/:id/games	id - a system internal player number (required) crypto_id - a players public fingerprint (alternative) page - a page number (optional)	Returns a set of 20 played games per page. Newest first.
GET /player/:id/accuracy	id - a system internal player number (required) crypto_id - a players public fingerprint (alternative) weapon - a weapon name, valid values are nex (default), shotgun, uzi, minstanex (optional)	A players accuracy stats. (Note: this resource always returns JSON)

> Player listings

Resource	Parameters	Description
GET /players	page - a page number (optional) sort - sort by join date (default) or nick (optional)	Returns ten player records per page. Newest first.

Examples:

• http://stats.xonotic.org/player/1.json
• http://stats.xonotic.org/player/NUdi+FneuxP8hBXFGI98ia9UxWT63UBFxR95WqNeNXo=.json
• http://stats.xonotic.org/player/NUdi+FneuxP8hBXFGI98ia9UxWT63UBFxR95WqNeNXo=/games.json?page=15

{}

• http://stats.xonotic.org/player/1/accuracy.json

{
   "player_id": 1,
   "player_url": "http://stats.xonotic.org/player/1",
   "weapon": "nex",
   "games": 20,
   "avg": 40.60,
   "accuracy": [("<game_id1>","<acc1>"), ("<game_id2>","<acc2>"), ("<game_idN>","<accN>")]
}

Games

Game listings

Resource	Parameters	Description
GET /games	page - a page number (optional)	Returns a set of 20 game records per page.

> Game records

Resource	Parameters	Description
GET /game/:game	game - a game number (required)	Returns a game record identified by an internal game number.

> Ranking info

Resource	Parameters	Description
GET /ranks/:gametype	gametype - a gametype shorthand, valid values are ctf, dm, tdm, duel (required) page - a page number (optional)	Returns a set of 20 ranked players for the given gametype. Top ranked first.

Examples:

• none

{}

Server

Server listings

Resource	Parameters	Description
GET /servers	page - a page number (optional)	Returns a list of 20 servers. Newest registered first.

> Server records

Resource	Parameters	Description
GET /server/:server	server - an internal server id (required) crypto_id - the servers public fingerprint (alternative)	Returns a server record by id or crypto-id.
GET /server/:server/games	server - an internal server id (required) crypto_id - the servers public fingerprint (alternative) page - a page number (optional)	Returns a set of 20 game records played on the given server. Latest first.

Examples:

• none

{}

Map

Map info

Resource	Parameters	Description
GET /maps	page - a page number (optional)	Returns a list of 20 known maps per page. Newest submitted first.

> Map info

Resource	Parameters	Description
GET /map/:map	map - an internal map id (required)	Returns a map recordset.

Examples:

• none

{}

Search

Search info

Resource	Parameters	Description
GET /search	nick - a player name string (?) server_name - a server name string (?) map_name - a map name string (?) dm - "on" (?) duel - "on" (?) ctf - "on" (?) tdm - "on" (?) fs - (?) gametype - a gametype shorthand, valid values are (an array of) ctf, dm, tdm, duel (?) page - a page number (optional)	Returns a search result (20 records). If the result contains more than 20 records, use page numbers to fetch them.

Examples:

• none

{}

Submission

This resource is strictly speaking not part of the public API.
It is only intended for access by cryptographically verified Xonotic game servers for stats submission, and the submission format is not documented here.

Resource	Parameters	Description
POST /stats/submit	Xonotic match POST data	Gameserver statistics sumission URL