API functions

Current API version v2.0

General

get
Get Plugin Name

api.getName()
Get the name of the plugin
Request
Response
Request
Response
200: OK
Returns the plugin name in a String
PowerRanks

get
Get API Version

api.getVersion()
Get the current API version. Can be used for compatibility checking.
Request
Response
Request
Response
200: OK
returns the API version in a string
"2.0"

Retrieving rank(s) / player(s)

get
Get Default Rank

api.getDefaultRank()
Get the default PRRank. Can be null if the default rank is missing
Request
Response
Request
Response
200: OK
Returns an PRRank
PRRank [object]
name: default

get
Get a rank by name

api.getRank(String rankName)
Get a specific PRRank by name Returns null if the rank is not found
Request
Response
Request
Path Parameters
rankName
required
string
The name of the rank to retrieve
Response
200: OK
Returns an PRRank
PRRank [object]
name: [rankName]

get
Get all ranks

api.getRanks()
Get all ranks that are available in PowerRanks
Request
Response
Request
Response
200: OK
Returns a collection of PRRanks
Collection<PRRank>

get
Get all rank names

api.getRankNames()
Get a collection of all rank names available in PowerRanks
Request
Response
Request
Response
200: OK
Returns a collection of Strings
Collection<String>

get
Get a player by name

api.getPlayer(String playerName)
Get a specific PRPlayer by name. Returns null if the player is not found
Request
Response
Request
Path Parameters
playerName
required
string
The name of the player to retrieve
Response
200: OK
Returns an PRRank
PRPlayer [object]
name: [playerName]

get
Get all players

api.getPlayers()
Get all players that are available in PowerRanks
Request
Response
Request
Response
200: OK
Returns a collection of PRPlayers
Collection<PRPlayer>

get
Get all player names

api.getPlayerNames()
Get the names of all players that are available in PowerRanks
Request
Response
Request
Response
200: OK
Returns a collection of Strings
Collection<String>

Rank specific functions

put
Create a new rank

api.createRank(String rankName)
Create a new rank and add it to the existing ranks
Request
Response
Request
Path Parameters
rankName
required
string
The name of the new rank to create
Response
200: OK
Returns PowerRanks API State
POWERRANKS_API_STATE.RANK_CREATE_SUCCESSFULLY
- the rank has successfully been created
304: Not Modified
Returns PowerRanks API State
POWERRANKS_API_STATE.RANK_CREATE_FAILED_INVALID_CHARACTERS
- The rank name does not match the required RegEx [^a-zA-Z0-9]
POWERRANKS_API_STATE.RANK_CREATE_FAILED_NAME_ALREADY_EXISTS
- A rank with that name already exists

put
Delete an existing rank

api.deleteRank(String rankName)
Delete an existing rank and remove it from storage. The default rank cannot be deleted. The deleted rank will be removed from all players who who that rank
Request
Response
Request
Path Parameters
rankName
required
string
The name of the rank to delete
Response
200: OK
Returns PowerRanks API State
POWERRANKS_API_STATE.RANK_DELETE_SUCCESSFULLY
- The rank has been deleted successfully
304: Not Modified
Returns PowerRanks API State
POWERRANKS_API_STATE.RANK_FAILED_CANNOT_DELETE_DEFAULT_RANK
- Attempted to delete the default rank
POWERRANKS_API_STATE.RANK_FAILED_NAME_NOT_FOUND
- A rank with that name is not found

put
Set a ranks weight

api.setRankWeight(String rankName, int weight)
Change the weight of a rank
Request
Response
Request
Path Parameters
rankName
required
string
The name of the rank to change the weight on
weight
required
integer
The new weight to set
Response
200: OK
Returns PowerRanks API State
POWERRANKS_API_STATE.POWERRANKS_API_STATE.RANK_SET_WEIGHT_SUCCESSFULLY
- The weight has been successfully modified
302: Found
Returns PowerRanks API State
POWERRANKS_API_STATE.RANK_FAILED_NAME_NOT_FOUND
- A rank with that name is not found

get
Get a ranks weight

api.getRankWeight(String rankName)
Get the weight of a rank
Request
Response
Request
Path Parameters
rankName
required
string
The name of the rank to retrieve the weight from
Response
200: OK
Returns an Integer with the weight of the rank Return 0 if the rank is not found
Integer
eg. 10

put
Set a ranks prefix

api.setRankPrefix(String rankName, String newPrefix)
Change the prefix of a rank
Request
Response
Request
Path Parameters
rankName
required
string
The name of the rank to change the prefix of
newPrefix
required
string
The new prefix. Enter an empty string to clear the prefix
Response
200: OK
Returns PowerRanks API State
POWERRANKS_API_STATE.RANK_SET_PREFIX_SUCCESSFULLY
- The prefix of the rank has been modified successfully
304: Not Modified
Returns PowerRanks API State
POWERRANKS_API_STATE.RANK_FAILED_NAME_NOT_FOUND
- A rank with that name was not found

get
Get a ranks prefix

api.getRankPrefix(String rankName)
Get the prefix of a rank
Request
Response
Request
Path Parameters
rankName
required
string
The name of the rank to retrieve the prefix from
Response
200: OK
String with the prefix of a rank Returns empty string if the rank is not found
String rank prefix
eg. "&0[&2default&0]&r"

put
Set a ranks suffix

api.setRankSuffix(String rankName String newSuffix)
Change the suffix of a rank
Request
Response
Request
Path Parameters
rankName
required
string
The name of the rank to change the suffix of
newSuffix
required
string
The new suffix. Enter an empty string to clear the suffix
Response
200: OK
Returns PowerRanks API State
POWERRANKS_API_STATE.RANK_SET_SUFFIX_SUCCESSFULLY
- The suffix of the rank has been modified successfully
304: Not Modified
Returns PowerRanks API State
POWERRANKS_API_STATE.RANK_FAILED_NAME_NOT_FOUND
- A rank with that name was not found

get
Get ranks suffix

api.getRankPrefix(String rankName)
Get the suffix of a rank
Request
Response
Request
Path Parameters
rankName
required
string
The name of the rank to retrieve the suffix from
Response
200: OK
String with the suffix of a rank Returns empty string if the rank is not found
String rank suffix
eg. "&0[&2default&0]&r"

Rank permissions

get
Get the ranks permissions

api.getRankPermissions(String rankName)
Returns a collection of PRPermissions for that rank
Request
Response
Request
Path Parameters
rankName
required
string
The name of the rank to retrieve the permissions from
Response
200: OK
Returns a collection of PRPermissions for that rank Returns empty collection if that rank is not found
Collection<PRPermission>

put
Add a permissions to a rank

api.addRankPermission(String rankName, String permission[, boolean allowed])
Add a permission in the format 'my.permission.node' to the specified rank
Request
Response
Request
Path Parameters
rankName
required
string
The name of the rank to add the permission to
permission
required
string
The permission node to add to the rank
allowed
optional
boolean
Should the permission be allowed or denied on that rank. When not given it defaults to allowed
Response
200: OK
Returns PowerRanks API State
POWERRANKS_API_STATE.RANK_PERMISSION_ADD_SUCCESSFULLY
- The permission has successfully been added to the rank
304: Not Modified
Returns PowerRanks API State
POWERRANKS_API_STATE.RANK_PERMISSION_ADD_FAILED_PERMISSION_ALREADY_EXISTS
- The permission too add already exist on that rank
POWERRANKS_API_STATE.RANK_FAILED_NAME_NOT_FOUND
- A rank with that name is not found

put
Add a permission to a rank

api.addRankPermission(String rankName, PRPermission permission)
Add a permission to the specified rank
Request
Response
Request
Path Parameters
rankName
required
string
The name of the rank to add the permission to
permission
required
object
The PRPermission object to add to the rank
Response
200: OK
Returns PowerRanks API State
POWERRANKS_API_STATE.RANK_PERMISSION_ADD_SUCCESSFULLY
- The permission has successfully been added to the rank
304: Not Modified
Returns PowerRanks API State
POWERRANKS_API_STATE.RANK_PERMISSION_ADD_FAILED_PERMISSION_ALREADY_EXISTS
- The permission too add already exist on that rank
POWERRANKS_API_STATE.RANK_FAILED_NAME_NOT_FOUND
- A rank with that name is not found

put
Remove a permission from a rank

api.RankPermission(String rankName, [String/PRPermission] permission)
Remove a permission from a rank. The permission can either be a String or a PRPermission
Request
Response
Request
Path Parameters
rankName
required
string
The rank to remove the permission from
permission
required
object
The permission to remove from the rank
Response
200: OK
Returns PowerRanks API State
POWERRANKS_API_STATE.RANK_PERMISSION_REMOVED_SUCCESSFULLY
- The permission is successfully removed from the specified rank
304: Not Modified
Returns PowerRanks API State
POWERRANKS_API_STATE.RANK_FAILED_NAME_NOT_FOUND
- A rank with that name is not found
POWERRANKS_API_STATE.RANK_FAILED_PERMISSION_NOT_FOUND
- The specified permission does not exist on the specified rank

put
Allow/deny an existing permission on a rank

api.setRankPermissionAllowed(String rankName, String permission, boolean allowed)
Change the allowance of a permission on a rank
Request
Response
Request
Path Parameters
rankName
required
string
The name of the rank to change a permission allowance on
permission
required
string
The permission node to change the permission allowance on
allowed
required
boolean
true: allowed false: defied
Response
200: OK
Returns PowerRanks API State
POWERRANKS_API_STATE.RANK_PERMISSION_ALLOWED_CHANGED_SUCCESSFULLY
- The allowance of the permission on the rank has been changed successfully
302: Found
Returns PowerRanks API State
POWERRANKS_API_STATE.RANK_FAILED_NAME_NOT_FOUND
- A rank with that name is not found
POWERRANKS_API_STATE.RANK_FAILED_PERMISSION_NOT_FOUND
- The specified permission does not exist on the specified rank

get
Check if a permission is allowed/denied on a rank

api.isRankPermissionAllowed(String rankName, String permission[, World world])
Check if a permission is allowed/denied on a rank When a world is specified it check if the permission is allowed in that world. Otherwise it checks the global permission allowance value.
Request
Response
Request
Path Parameters
rankName
required
string
The name of the rank to check the permissions allowance on
permission
required
string
The permission node to check the allowance value on
world
optional
object
The Bukkit world object to check the permission allowance on
Response
200: OK
Returns Boolean with the allowance value
true: permission is allowed
false: permission is denied

Player specific functions

put
Overwrite a players ranks

api.setPlayerRank(String playerName, String rankName)
Remove all ranks from the player except the default rank and add the new rank
Request
Response
Request
Path Parameters
playerName
required
string
The name of the player to overwrite the ranks from
rankName
required
string
The name of the rank to set to the player
Response
200: OK
Returns PowerRanks API State
POWERRANKS_API_STATE.PLAYER_SUCCESSFULLY_SET_RANK
- Successfully changed the ranks of the player to this one
304: Not Modified
Returns PowerRanks API State
POWERRANKS_API_STATE.RANK_FAILED_NAME_NOT_FOUND
- A rank with that name is not found
POWERRANKS_API_STATE.PLAYER_FAILED_NAME_NOT_FOUND
- A player with that name is not found
POWERRANKS_API_STATE.PLAYER_FAILED_ALREADY_HAS_RANK
- Cannot add the rank, the player already has that rank

put
Add a rank to a player

api.addPlayerRank(String playerName, String rankName)
Add a rank to the player
Request
Response
Request
Path Parameters
playerName
required
string
The name of the player to add the rank to
rankName
required
string
The name of rank to add to the player
Response
200: OK
Returns PowerRanks API State
POWERRANKS_API_STATE.PLAYER_SUCCESSFULLY_ADDED_RANK
- Successfully added the rank to the player
304: Not Modified
Returns PowerRanks API State
POWERRANKS_API_STATE.RANK_FAILED_NAME_NOT_FOUND
- A rank with that name is not found
POWERRANKS_API_STATE.PLAYER_FAILED_NAME_NOT_FOUND
- A player with that name is not found
POWERRANKS_API_STATE.PLAYER_FAILED_ALREADY_HAS_RANK
- Cannot add the rank, the player already has that rank

put
Remove a rank from a player

api.removePlayerRank(String playerName, String rankName)
Remove a rank from the player
Request
Response
Request
Path Parameters
playerName
required
string
The target player to remove the rank from
rankName
required
string
The name of the rank to remove from the player
Response
200: OK
Returns PowerRanks API State
POWERRANKS_API_STATE.PLAYER_SUCCESSFULLY_REMOVED_RANK
- The rank has been removed from the player
304: Not Modified
Returns PowerRanks API State
POWERRANKS_API_STATE.RANK_FAILED_NAME_NOT_FOUND
- A rank with that name is not found
POWERRANKS_API_STATE.PLAYER_FAILED_NAME_NOT_FOUND
- A player with that name is not found
POWERRANKS_API_STATE.PLAYER_FAILED_DOES_NOT_HAVE_RANK
- The player does not have that rank
POWERRANKS_API_STATE.RANK_FAILED_CANNOT_DELETE_DEFAULT_RANK
- Cannot delete the default rank from the player

get
Remove all players ranks except default

api.clearRanks(String playerName)
Reset a player's ranks to default. The specified players ranks will be removed and only the default rank will remain.
Request
Response
Request
Path Parameters
playerName
required
string
The target player to clear the ranks from
Response
200: OK
Returns PowerRanks API State
POWERRANKS_API_STATE.PLAYER_SUCCESSFULLY_REMOVED_ALL_RANKS
- The player's ranks have been reset
304: Not Modified
Returns PowerRanks API State
POWERRANKS_API_STATE.PLAYER_FAILED_NAME_NOT_FOUND
- A player with that name is not found