Index - MxKarma

Warning: Keep in mind this API is not yet in its final form and may change at any time. If developing, it is strongly recommended to contact an administrator to ensure your application does not accidentally get flagged for spoofing and to be notified about changes!

API Documentation

The MXKarma API controller is a simple REST-like API.
Some operations (such as submitting new karma scores) require an API key. A separate API key is required for each server. An API key can be used to start a session, which yields you a session key, which is then a required parameter at some operations.
All responses are JSON-serialized objects of the following result:

success boolean - True if the request was succesful, false if an error occured.
data object - The method its response object if the request was succesful, otherwise the error object.

All API requests should be submitted to https://karma.mania-exchange.com/api2/{methodName}?{parameters}.

POST requests are sometimes used if the data structure is more complex. The content of POST requests are always JSON-serialized.
The content-type has to be set to application/json.

Program flow

When used together with a controller, the following program flow should be followed to ensure performance:

startSession called
activateSession called, if succesfully authed, continue forever with:
1. saveVotes once per map to import votes from an existing local source. (Optional)
2. getMapRating once a map starts to get current votes, optinally providing an array of player logins whose votes should be looked up.
3. getMapRating once one or more players connected to look up their votes. It it recommended to have a timeout between multiple of these calls and cache newly connected players. (Optional)
4. saveVotes once a map ends (only send changed votes!).

Method documentation

GET startSession

Description

Given server login and some additional information, creates a new session for the specified server. A session key and session seed are returned. The session is not activated at time of creation, this has to be done using the session seed and api key in a following activateSession request.

Parameters

serverLogin string - The server login.
applicationIdentifier string - The application identifier (e.g. controller name & version).
testMode boolean - Set to true while testing only.

Return structure

sessionKey string - The session key.
sessionSeed string - The session seed.

GET activateSession

Description

Given a hash from the api key and session seed, and a session key obtained from startSession, activates the session for write operations. Once a session is succesfully activated, other activated sessions are closed. If a session failed to activate, the session is closed immediately.

Parameters

sessionKey string - The session key.
activationHash string - The activation hash, generated by taking the sha512 of the api key and the session seed concatenated ( sha512(apiKey + sessionSeed) ), hex-encoded as a string. Capitalisation and dashes do not matter.

Return structure

activated boolean - Always true, if activation failed, an error is returned instead.

POST getMapRating

Description

Given a map its unique ID, a gamemode and titlepack, returns the amount of votes and the average vote.
An array of logins can be specified to get the ratings these players made, if any.
In case only the votes result field is important, set the getvotesonly value to true!

Parameters

sessionKey string - The session key.

POST-content structure

gamemode string - Gamemode. Provide GetScriptName() in case of a scripted mode. For hardcoded TrackMania modes, provide the suiting string from the set {Rounds, TimeAttack, Team, Laps, Cup, Stunts}.
titleid string - Titlepack (also known as a TitleId).
mapuid string - Map its UID.
getvotesonly boolean - If true, only the votes in playerlogins will be looked up. Should be true in case of requesting the values of e.g. newly joined players.
playerlogins array - Array of strings containing player logins whose votes should be looked up. (Maximum of 100.)

Return structure

votecount number - Amount of votes made so far.
voteaverage number - Average vote. If no votes are made, this value equals 50. Not per see integeral.
modevotecount number - Amount of votes made so far in the current mode/title group. If getvotesonly, this value equals -1.
modevoteaverage number - Average vote in the current mode/title group. If no votes are made, this value equals 50. If getvotesonly, this value equals -1. Not per see integeral.
votes array - Array of objects containing votes of the requested logins.
- login string - Player login.
- vote number - Player vote (integer ranging from 0 to 100). Player logins provided who have not voted are not included here.

POST saveVotes

Description

Given a map, gamemode, titlepack and an array of players who changed or added a new vote, saves the votes.
Note: Only changed votes should be submitted, do not send the whole collection of votes again!
Note: Make sure to call this method at reasonable times, such as once the map ends (EndMap callback) send all changed votes and not at every single vote!
Note: Only a single import per map per server is allowed, the client should track imports made as well!
Note: Only locally saved karma-imports are allowed!

Parameters

sessionKey string - The session key.

POST-content structure

gamemode string - Gamemode. Provide GetScriptName() in case of a scripted mode. For hardcoded TrackMania modes, provide the suiting string from the set {Rounds, TimeAttack, Team, Laps, Cup, Stunts}.
titleid string - Titlepack (also known as a TitleId).
mapuid string - Map its UID.
mapname string - Map its raw name. Please do not strip styling!
mapauthor string - Map its author login.
isimport boolean - In case you import existing votes to the global database, set this parameter to true!
maptime number - Integeral map time in seconds, the time from BeginMap to EndMap. If importing, set this value to 0.
votes array - Array of objects containing changed and/or new votes made.
- login string - Player login.
- nickname string - Player nickname. Please do not strip styling!
- vote number - Player vote (integer ranging from 0 to 100).

Return structure

updated boolean - True if votes have been updated.

Errors

In case of an error, the success field of the return object will be false and data contains the following object:

Error object structure

code number - Integeral error code, should be used to identify the action after an error.
message string - Short error message.

Possible errors are listed below.

Code	Message & details	Thrown at
1	internal server error Internal server error.	Anywhere
2	invalid session Session key is invalid (not activated, experied or got disabled).	activateSession, getMapRating, saveVotes
3	lacking parameters Some parameters are not provided.	startSession, activateSession
4	invalid api key API key not found or suspended.	activateSession
5	invalid server Server not found or suspended.	startSession, activateSession, saveVotes
6	server is banned Server is banned.	startSession
7	session origin and request mismatch Cross-server call rejected.	activateSession, getMapRating, saveVotes
8	invalid hash Invalid activation hash provided, session closed.	activateSession
9	session already activated Session already active.	activateSession
10	unsupported content-type Unsupported Content-Type.	getMapRating, saveVotes
11	too many logins Too many logins requested.	getMapRating
12	invalid format Invalid JSON or invalid structure.	getMapRating, saveVotes
13	votes rejected Malformed vote request.	saveVotes
14	no votes cast - please do not make requests if there are no votes! No votes cast.	saveVotes
15	too many import votes - request a limit raise if needed Too many imports.	saveVotes
16	import rejected Import rejected.	saveVotes