REST (Representational State Transfer) is an architectural style for providing standards between computer systems on the web. It differs from the MBedwars API as that you don't need a plugin/addon to run on the game server. Instead, you may have a seperate software that accesses the MBedwars API in a HTTP-like matter, with the content being structured as JSON.
Creating the web API is straightforward, although note that it requires Java 11 or newer to run. It is available as a Spigot plugin (download), which you may either drop-in inside your /plugins/MBedwars/add-ons or /plugins folder.
After restarting your server, a new file within /plugins/MBedwars/add-ons/RestApi/config.yml will appear. It holds the following content:
# Used for auto-updating the config file. Ignore it
file-version: 2
# Address and port of the http server
# Use of a reverse proxy for https is recommended
host: localhost
port: 8084
# The list of users that are allowed to have access
# All available permissions (wildcard * is NOT supported):
# - arenas.read
# - servers.read
# - players.read.online
# - players.stats.read
# - players.stats.read.rank
# - players.stats.read.leaderboard
# - players.stats.read.sets
# - players.stats.write
# - players.achievements.read
# - players.achievements.read.types
# - players.achievements.read
# - players.properties.read
# - players.properties.write
users:
- username: "default"
password: "CtYZFmuPHRCuhNKQA4be4Yy2U4BVR7"
permissions:
- arenas.read
- servers.read
- players.read.online
- players.stats.read
- players.stats.read.rank
- players.stats.read.leaderboard
- players.stats.read.sets
- players.stats.write
- players.achievements.read
- players.achievements.read.types
- players.properties.read
- players.properties.write
# The list of allowed CORS origins. It adds an extra layer of security
# It basically refers to the allowed domains that can access the API
# You may see an "Cross-Origin Request Blocked" error if it's not configured correctly
# Use * to allow all origins
allowed-cors-origins: [ ]
With each new installation, a new user with a randomly generated password will be created. It holds all existing permissions. Note that the permissions work differently than the permissions that you are used with Spigot plugins. E.g. wildcard * won't work, each permission must be specifically given. It is recommended to create a new user for each application to avoid potential leaks and attacks.
In case you didn't modify the address and are running the Spigot server locally on your PC, you may test its functionality by visting http://localhost:8084. It may fail if that address is already taken by another application, check your logs. You will see the following page:
{
"motd": "Hello world! The MBedwars REST server is up and running. See the wiki and specification for more information.",
"version": "1.0",
"productWebsite": "https://mbedwars.com/",
"documentationWiki": "https://wiki.mbedwars.com/",
"documentationSpecification": "https://wiki.mbedwars.com/en/Development/REST-API",
"authenticatedUserPermissions": []
}
We greatly recommend to use a reverse proxy during production to make use of HTTPS. Additionally, you may also access the documentation by visiting http://localhost:8084/redoc.
Next, you may implement the required client. For that, you may automatically generate the necessary files using the OpenAPI generator, which is available for basically any language. The required schema can be downloaded from the API Docs.