REST API
In TNE's Web Module, we provide a REST API, which allows external applications to interact with a server that uses TNE for its economy. The most notable interaction is through the Official TNE Android app. This page outlines the various API functionality and documents the correct usage.
In order to keep every server's economy as secure as possibly, all interactions with the API will require a user's SessionID, which is obtained through a SessionCreationRequest. Please note: Session IDs expire after 30 minutes.
The following documents every request, also referred as API method in this page, that is supported in the REST API. Each with the appropriate API version. Please use the correct URL, as listed below, for the correct API version.
| API Version | BASE URL to send request |
|---|---|
| v1 | /api-v1/ |
We use some definitions on this page to describe various parts of the API, and how to properly use it. For your convenience, and to make everything as clear as possible, below is a table of definitions used throughout this page that may be confusing to some individuals.
| Word | Definition |
|---|---|
| Object | An object is a JSON-formatted message sent to the API URL, or received during a response from the API. |
Every object used to call an API method should contain the following parameters.
| Name | Description |
|---|---|
| SessionID | The UUID, in string format, obtained from the SessionCreationRequest. |
| Controller | The UUID, in string format, that corresponds to the account used in SessionCreationRequest. |
Every response object will minimally have a Response Status Object. This object contains predefined types notated as a "status."
| Status | Definition |
|---|---|
| FAILED | The call to the API method returned a failed response, which means you won't receive the anticipated object. |
| SUCCESS | The call to the API method was successful, and has returned the correct response object. |
| INSECURE | The provided Session ID does not match the username provided in the SessionID, and controller parameters. |
The session creation request is used to properly identify the owner of the account that you wish to use for your calls to the REST API. This is used to prevent malicious players from freely interacting with the API, without haven't the relevant permissions on the server. I.e. players can't use the API to give other players money without having the permission node for the /money give command.
/session/create
This is the object sent to the API URL in order to receive a response.
{
"AccountID": "The String representation of the UUID of the TNE Account being used to call the API.",
"Pin": "The pin set for the TNE Account being used to call the API."
}
This is the object returned if Response Status is SUCCESS.
{
"SessionID": "The String representation of the Session UUID created for this request."
}
Used to create an account, with an optional default balance parameter.
/account/create
POST
This is the object sent to the API URL in order to receive a response.
{
"Controller": "The UUID, in string format, that corresponds to the account used in SessionCreationRequest.",
"SessionID": "The UUID, in string format, obtained from the SessionCreationRequest.",
"Identifier": "The identifier for the account. This could be a username, UUID, etc",
//Default holdings for this account, completely optional.
"Holdings": {
"World": "The world name to use for this holdings value, empty string for default.",
"Currency": "The currency name to use for this holdings value, empty string for default.",
"Amount": "The amount to use for this holdings value."
}
}
This is the object returned if Response Status is SUCCESS.
{
"Status": "SUCCESS if created, otherwise FAILED.",
"AccountID": "The String form of the UUID for the TNE Account, if created."
}
Used to check whether an account exists or not.
/account/exists
GET
This is the object sent to the API URL in order to receive a response.
{
"Controller": "The UUID, in string format, that corresponds to the account used in SessionCreationRequest.",
"SessionID": "The UUID, in string format, obtained from the SessionCreationRequest.",
"Identifier": "The identifier for the account. This could be a username, UUID, etc",
}
This is the object returned if Response Status is SUCCESS.
{
"Status": "SUCCESS if exists, otherwise FAILED.",
"AccountID": "The String form of the UUID for the TNE Account, if it exists."
}
Used to delete an account.
/account/delete
DELETE
This is the object sent to the API URL in order to receive a response.
{
"Controller": "The UUID, in string format, that corresponds to the account used in SessionCreationRequest.",
"SessionID": "The UUID, in string format, obtained from the SessionCreationRequest.",
"Identifier": "The identifier for the account. This could be a username, UUID, etc",
}
This is the object returned if Response Status is SUCCESS.
{
"Status": "SUCCESS if deleted, otherwise FAILED.",
"Message": "The failed message if Status is FAILED."
}
Used to get an account object, which contains various information about an economy account.
/account/get
GET
This is the object sent to the API URL in order to receive a response.
{
"Controller": "The UUID, in string format, that corresponds to the account used in SessionCreationRequest.",
"SessionID": "The UUID, in string format, obtained from the SessionCreationRequest.",
"Identifier": "The identifier for the account. This could be a username, UUID, etc",
}
This is the object sent to the API URL in order to receive a response.
{
"Status": "SUCCESS if the account exists, otherwise FAILED."
"Identifier": "The UUID for the account.",
"Display": "The username for the account.",
"Player": "True if the account belongs to a player, otherwise false.",
"Language": "The language set for this account.",
"Joined": "The long representation of the date this account was created.",
"LastOnline": "The long representation of the date the owner of this account, if player is true, was last online.",
//List of the account's holdings.
"Holdings": {
"World": "The world name to use for this holdings value, empty string for default.",
"Currency": "The currency name to use for this holdings value, empty string for default.",
"Amount": "The amount to use for this holdings value."
}
}
xxxxxxxx