REST API v3 #6
Description
TShock's REST API v2 is out for quite some time now and it would be nice to have a next version. This gives room to fix some inconsistencies, remove duplication, fix issues and add features.
For example purposes, I will use 127.0.0.1 for the host and 7878 for the REST port. Also, because JSON does not officially support comments, I "faked" the comments.
Consistency
Base URL
One issue we currently face is that you have to use v1 for some endpoints and for some other endpoints v2. In v3 everything should be called from http://127.0.0.1:7878/v3/.
Keys
Keys MUST be lower_under.
Values
A value SHOULD NOT contain multiple values. buffs from REST v2 is a good example of how it should not be done.
{
"//": "...",
"buffs": "147, 86, 158, 146, 87, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0"
}Dates
All dates SHOULD be available as specified in ISO 8601.
Complete date plus hours and minutes:
YYYY-MM-DDThh:mmTZD (eg 1997-07-16T19:20+01:00)
Security
GET can expose sensitive data. And besides,
the convention has been established that the GET and HEAD methods SHOULD NOT have the significance of taking an action other than retrieval. These methods ought to be considered "safe".
— http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1
Like in v1 and v2, the token should not be in the URL.
Usernames, passwords, session tokens, and API keys should not appear in the URL, as this can be captured in web server logs, which makes them intrinsically valuable.
Endpoints
Tokens
Generating a token
Deprecates: /token/create
http://127.0.0.1:7878/v3/token/generate
data:
username = 'restuser'
password = 'restpass'
Example response:
{
"status": 201,
"response": "Successfully generated token.",
"data": {
"token": "5C58D5332D5A51DCC5CFFEBD3813014ECF0248BA104CF12ADE0F93E192E77347",
"expiration_date": "2015-7-24T13:39Z"
}
}Validating a token
Deprecates: /tokentest
http://127.0.0.1:7878/v3/token/validate
data:
token = '5C58D5332D5A51DCC5CFFEBD3813014ECF0248BA104CF12ADE0F93E192E77347'
Example response:
{
"status": 200,
"response": "Token is valid.",
"data": {
"token": "5C58D5332D5A51DCC5CFFEBD3813014ECF0248BA104CF12ADE0F93E192E77347",
"expiration_date": "2015-7-24T13:39Z"
}
}Server
Information
Deprecates: /v2/status, /v2/server/status
http://127.0.0.1:7878/v3/server/info
data:
token = '5C58D5332D5A51DCC5CFFEBD3813014ECF0248BA104CF12ADE0F93E192E77347'
Example response:
{
"status": 200,
"data": {
"name": "TerraServer",
"host": "127.0.0.1",
"port": "7777",
"software": {
"name": "tshock",
"version": "4.4.0"
}
}
}Executing a command
Deprecates: /v2/server/rawcmd, /v2/world/butcher, /world/meteor, /world/bloodmoon/{bool}, /v2/players/kick, /v2/players/kill, /v2/players/mute, /v2/players/unmute, /v2/world/save, /v2/server/broadcast
http://127.0.0.1:7878/v3/server/execute-command
data:
token = '5C58D5332D5A51DCC5CFFEBD3813014ECF0248BA104CF12ADE0F93E192E77347'
command = 'time noon'
Example response:
{
"status": 200,
"response": "Server set the time to 12:00."
}Changing server password
http://127.0.0.1:7878/v3/server/update-password
data:
token = '5C58D5332D5A51DCC5CFFEBD3813014ECF0248BA104CF12ADE0F93E192E77347'
password = '123123'
Example response:
{
"status": 200,
"response": "Successfully changed server password."
}Shutting the server down
Deprecates: /v2/server/off
http://127.0.0.1:7878/v3/server/shut-down
data:
token = '5C58D5332D5A51DCC5CFFEBD3813014ECF0248BA104CF12ADE0F93E192E77347'
save = false // Optional; default true
Example response:
{
"status": 200,
"response": "Server shut down. World not saved."
}Starting the server up
New feature
http://127.0.0.1:7878/v3/server/start-up
data:
token = '5C58D5332D5A51DCC5CFFEBD3813014ECF0248BA104CF12ADE0F93E192E77347'
port = 8888 // Optional; default 7777
Example response:
{
"status": 200
}World
Information
Deprecates: /world/read, /v2/server/status
http://127.0.0.1:7878/v3/world
data:
token = '5C58D5332D5A51DCC5CFFEBD3813014ECF0248BA104CF12ADE0F93E192E77347'
Example response:
{
"status": 200,
"data": {
"id": 18624254254,
"name": "World 3",
"size": {
"type": "medium",
"width": 6400,
"height": 1800
},
"mode": "expert",
"creation_date": "2015-7-24T13:39Z",
"//": "In what format is the time??",
"time": "42149",
"is_day": true,
"is_bloodmoon": false,
"//": "TODO: Improve invasionsize.",
"invasionsize": 0
}
}Auto-saving
Deprecates: /v2/world/autosave/state/{bool}
http://127.0.0.1:7878/v3/world/auto-save
data:
token = '5C58D5332D5A51DCC5CFFEBD3813014ECF0248BA104CF12ADE0F93E192E77347'
mode = false // Optional; default true
Example response:
{
"status": 200,
"response": "Successfully set auto-save to true."
}Groups
Group information
Deprecates: /v2/groups/list, /v2/groups/read
http://127.0.0.1:7878/v3/groups
data:
token = '5C58D5332D5A51DCC5CFFEBD3813014ECF0248BA104CF12ADE0F93E192E77347'
Example response:
{
"status": 200,
"response": "Successfully fetched 8 groups.",
"data": {
"groups": [
{
"name": "default",
"parent": "guest",
"rgb_chat_color": [
255,
255,
255
],
"permissions": [
"tshock.reservedslot"
],
"negatedpermissions": [],
"totalpermissions": [
"tshock.reservedslot",
"tshock.warp",
"// ...",
"tshock.canchat"
]
},
"// ..."
]
}
}Create group
Deprecates: /v2/groups/create
http://127.0.0.1:7878/v3/group/create
data:
token = '5C58D5332D5A51DCC5CFFEBD3813014ECF0248BA104CF12ADE0F93E192E77347'
name = 'Team Penguin'
prefix = '(Team Penguin)'
suffix = null
parent_type = 'id' // Optional; defaults to "name"; options: id, name
parent_group = 23
permissions = [
'tshock.tp.self',
'tshock.tp.others'
]
rgb_chat_color = [
255,
255,
255
]
Example response:
{
"status": 201,
"response": "Successfully created group \"Team Penguin\"."
}Update group
Deprecates: /v2/groups/update
http://127.0.0.1:7878/v3/group/update
data:
token = '5C58D5332D5A51DCC5CFFEBD3813014ECF0248BA104CF12ADE0F93E192E77347'
type = 'id' // Optional; defaults to "name"; options: id, name
name = 24
prefix = '(Team Penguin)'
suffix = null
parent_type = 'id' // Optional; defaults to "name"; options: id, name
parent_group = 23
permissions = [
'tshock.tp.self',
'tshock.tp.others'
]
rgb_chat_color = [
255,
255,
255
]
Example response:
{
"status": 201,
"response": "Successfully created group \"Team Penguin\"."
}Delete group
Deprecates: /v2/groups/destroy
http://127.0.0.1:7878/v3/group/delete
data:
token = '5C58D5332D5A51DCC5CFFEBD3813014ECF0248BA104CF12ADE0F93E192E77347'
type = 'id' // Optional; defaults to "name"; options: id, name
group = 24
Example response:
{
"status": 200,
"response": "Successfully deleted group \"Team Penguin\"."
}Users
Registered users info
Relevant: Pryaxis/TShock#901
Deprecates: /v2/users/read
http://127.0.0.1:7878/v3/users
data:
token = '5C58D5332D5A51DCC5CFFEBD3813014ECF0248BA104CF12ADE0F93E192E77347'
Example response:
{
"status": 200,
"response": "Successfully fetched 4 online users.",
"data": {
"maximum_allowed": 7,
"online": [
{
"nickname": "Ped",
"username": "ped",
"group": "superadmin",
"team": 0,
"ip": "127.0.0.1",
"position": {
"longtitude": 3219,
"latitude": 290
},
"buffs": [
{
"id": 147,
"name": "Banners",
"description": [
"Increased damage and defense from the following:",
"Zombie",
"Green Slime"
],
"seconds_left": null
},
{
"id": 121,
"name": "Fishing",
"description": "Increased fishing level",
"seconds_left": 480
}
],
"inventory": {
"items": [
{
"id": 200,
"name": "Green Phaseblade",
"description": [
"23 melee damage",
"9% critical strike chance",
"Fast speed",
"Weak knockback",
"Material",
"+5% damage",
"+15% knockback"
],
"prefix": {
"id": 7,
"name": "Unpleasant"
},
"amount": 1
},
"// x50 elements"
],
"coins": [
"// Same as items, but without prefix",
"// x4 elements"
],
"ammo": [
"// Same as items, but without prefix",
"// x4 elements"
],
"trash": null,
"holding_item": null,
"helmet": {
"dye": {
"id": 213,
"name": "Brown Dye",
"description": [
"Material"
]
},
"vanity": {
"//": "Same as dye, but with prefix",
"prefix": {
"id": 7,
"name": "Unpleasant"
}
},
"item": {
"//": "Same as dye, but with prefix",
}
},
"shirt": {
"//": "Same as helmet"
},
"pants": {
"//": "Same as helmet"
},
"accessories": [
{
"dye": {
"//": "Same as helmet's dye"
},
"vanity": {
"//": "Same as helmet's vanity"
},
"item": {
"//": "Same as dye, but with prefix"
}
}
"// x5 elements"
],
"pet": {
"dye": {
"//": "Same as helmet's dye"
},
"item": {
"//": "Same as helmet's item"
}
},
"light_pet": {
"//": "Same as pet"
},
"mount": {
"//": "Same as pet"
},
"minecart": {
"//": "Same as pet"
},
"grappling_hook": {
"//": "Same as pet"
}
}
},
"// Other players"
]
}
}Online info
Relevant: Pryaxis/TShock#901
Deprecates: /v2/server/status, /v2/users/activelist, /v2/players/read, /v2/players/list
http://127.0.0.1:7878/v3/online-users
data:
token = '5C58D5332D5A51DCC5CFFEBD3813014ECF0248BA104CF12ADE0F93E192E77347'
Example response:
{
"status": 200,
"response": "Successfully fetched 4 online users.",
"data": {
"maximum_allowed": 7,
"online": [
{
"nickname": "Ped",
"username": "ped",
"group": "superadmin",
"team": 0,
"ip": "127.0.0.1",
"position": {
"longtitude": 3219,
"latitude": 290
},
"buffs": [
{
"id": 147,
"name": "Banners",
"description": [
"Increased damage and defense from the following:",
"Zombie",
"Green Slime"
],
"seconds_left": null
},
{
"id": 121,
"name": "Fishing",
"description": "Increased fishing level",
"seconds_left": 480
}
],
"inventory": {
"items": [
{
"id": 200,
"name": "Green Phaseblade",
"description": [
"23 melee damage",
"9% critical strike chance",
"Fast speed",
"Weak knockback",
"Material",
"+5% damage",
"+15% knockback"
],
"prefix": {
"id": 7,
"name": "Unpleasant"
},
"amount": 1
},
"// x50 elements"
],
"coins": [
"// Same as items, but without prefix",
"// x4 elements"
],
"ammo": [
"// Same as items, but without prefix",
"// x4 elements"
],
"trash": null,
"holding_item": null,
"helmet": {
"dye": {
"id": 213,
"name": "Brown Dye",
"description": [
"Material"
]
},
"vanity": {
"//": "Same as dye, but with prefix",
"prefix": {
"id": 7,
"name": "Unpleasant"
}
},
"item": {
"//": "Same as dye, but with prefix",
}
},
"shirt": {
"//": "Same as helmet"
},
"pants": {
"//": "Same as helmet"
},
"accessories": [
{
"dye": {
"//": "Same as helmet's dye"
},
"vanity": {
"//": "Same as helmet's vanity"
},
"item": {
"//": "Same as dye, but with prefix"
}
}
"// x5 elements"
],
"pet": {
"dye": {
"//": "Same as helmet's dye"
},
"item": {
"//": "Same as helmet's item"
}
},
"light_pet": {
"//": "Same as pet"
},
"mount": {
"//": "Same as pet"
},
"minecart": {
"//": "Same as pet"
},
"grappling_hook": {
"//": "Same as pet"
}
}
},
"// Other players"
]
}
}Create user
Deprecates: /v2/users/create
http://127.0.0.1:7878/v3/user/create
data:
token = '5C58D5332D5A51DCC5CFFEBD3813014ECF0248BA104CF12ADE0F93E192E77347'
username = 'ped'
password = '123123'
group = 'moderator' // Optional; defaults to "default"
Example response:
{
"status": 201,
"response": "Successfully created moderator \"ped\"."
}Update user
Deprecates: /v2/users/update
http://127.0.0.1:7878/v3/user/update
data:
token = '5C58D5332D5A51DCC5CFFEBD3813014ECF0248BA104CF12ADE0F93E192E77347'
type = 'id' // Optional; defaults to "username"; options: id, username
user = 254
// TODO: Add more parameters
Example response:
{
"status": 200,
"response": "Successfully updated user 254."
}Delete user
Deprecates: /v2/users/destroy
http://127.0.0.1:7878/v3/user/delete
data:
token = '5C58D5332D5A51DCC5CFFEBD3813014ECF0248BA104CF12ADE0F93E192E77347'
type = 'id' // Optional; defaults to "username"; options: id, username
user = 254
Example response:
{
"status": 200,
"response": "Successfully deleted user from database."
}Bans
Deprecates: /v2/players/ban
REST API v1 & v2
v1 is out for a very long time. I propose to remove the support to get rid of legacy code. I also propose to deprecate v2 and remove it in August 2018.
Feel free to comment on this. I might have missed something or made some mistakes along the way.
@WhiTexz If v3 is already out, then you can obviously name it v4. I am not aware of v3.