API - Gamocosm/Gamocosm GitHub Wiki
A simple HTTP API was discussed and added for GitHub issue #98. It has been used for a couple Discord bots (that I am aware of):
You can check them out for examples.
The routes are defined in config/routes.rb, and handled in app/controllers/api_controller.rb.
The URLs are of the following format.
https://gamocosm.com/servers/<your server UUID>/api/<API key>/<action>
Your API key is shown under the "Advanced Tab" of your server page.
As of 2023 July 28, there are 8 actions. They all return JSON dictionaries. The response code should always be 200; see below on handling errors.
The status endpoint responds to GET requests and should always succeed (given a valid server UUID and API key).
It returns a dictionary with the following string keys:
-
server: a boolean indicating whether the Digital Ocean server is running or not. -
status: a string for any pending operation (e.g.starting). -
minecraft: a boolean indicating whether the Minecraft server is running or not. -
ip: a string containing the IP address of the server (or null). -
domain: a string containing the Gamocosm user servers domain of the server. It should never be null. -
download: a string containing the download URL for the Minecraft world. It will be null if the Digital Ocean server is not running.
For example:
# curl https://gamocosm.com/servers/1234/api/5678/status
{"server":false,"status":null,"minecraft":false,"ip":null,"domain":"abcd.users.gamocosm.com","download":null}
The remaining 7 actions respond to POST requests.
The request HTTP header Content-Type should be set to application/json.
They always return a JSON dictionary containing a single string key: error.
If error is null, then the action succeeded; otherwise, it will be an error message (string).
These 6 actions do not take any additional data.
-
start, -
stop, -
reboot, -
resume, -
pause, and -
backup(perform a local backup of the current world on the Digital Ocean server).
When using curl, the --data flag (followed by a (possibly empty) string) can be used to perform a POST request.
If you forget the --data flag, curl will perform a GET request and Gamocosm will return a 404 response.
If you don't pass an empty string after --data, curl will consume the next argument (presumably the Gamocosm URL) as the data,
and will probably fail (e.g. no URL specified!).
Since these actions don't actually pass any data, the Content-Type header can be omitted.
For example:
# curl --data '' https://gamocosm.com/servers/1234/api/5678/stop
{"error":"Server already stopped"}
Finally, the exec action requires a JSON dictionary with a single string key command (and string value).
It runs the command on the Minecraft server.
For example:
# curl --header 'Content-Type: application/json' --data '{"command: "op MinecraftUsername"}' https://gamocosm.com/servers/1234/api/5678/start
{"error":null}