Skip to content
This repository has been archived by the owner on Jun 14, 2024. It is now read-only.

REST API

Daniel V edited this page Jun 22, 2019 · 3 revisions

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.

Security

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.

Requests

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/

Definitions

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.

Standard Object Parameters

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.

Response Status Object

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.

Session Creation Request

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.

URL

/session/create

Sent Object

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."
}

Returned Object

This is the object returned if Response Status is SUCCESS.

{
"SessionID": "The String representation of the Session UUID created for this request."
}

Account Creation Request

Used to create an account, with an optional default balance parameter.

URL

/account/create

Request Type

POST

Sent Object

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."
}
}

Returned Object

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."
}

Account Exists Request

Used to check whether an account exists or not.

URL

/account/exists

Request Type

GET

Sent Object

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",
}

Returned Object

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."
}

Account Delete Request

Used to delete an account.

URL

/account/delete

Request Type

DELETE

Sent Object

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",
}

Returned Object

This is the object returned if Response Status is SUCCESS.

{
"Status": "SUCCESS if deleted, otherwise FAILED.",
"Message": "The failed message if Status is FAILED."
}

Account Get Request

Used to get an account object, which contains various information about an economy account.

URL

/account/get

Request Type

GET

Sent Object

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",
}

Returned Object

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."
}
}