/api/servers/

Use: Gives you a list of information about all public servers. If you're authenticated, you will also be given each server's IP, Port, and the mppass you need to authenticate with the server.

Note: T1 country abbreviation is used when geo IP lookup on a server is unsuccessful.

Usage

Send a GET request to /api/servers/ to get a json list of all public servers.

< GET /api/servers/

> { "servers" : [
>	{"hash": "700a2e3072c9d3b4fa34f5446f6845e8", "maxplayers": 20, "name": "Lava survival", "players": 0, "software": "MCDzienny", "uptime": 216392, "country_abbr": "US"},
>	{"hash": "a709fabdf836a2a102c952442bf2dab1", "maxplayers": 70, "name": "Freebuild server", "players": 5, "software": "MCGalaxy", "uptime": 185447, "country_abbr": "CA"},
>	{"hash": "408530cd2967a7d9629b992eac4d927c", "maxplayers": 50, "name": "Freebuild 24/7", "players": 2, software: "ProCraft", "uptime": 122356, "country_abbr": "DE"},
>	{"hash": "9a55a83a2bd9f87562fd562a17abcdf0", "maxplayers": 15, "name": "Zombie survival", "players": 1, software: "", "uptime": 84952, "country_abbr": "GB"},
>	{"hash": "23860c5e192cbaa4698408338efd61cc", "maxplayers": 30, "name": "Other server", "players": 0, software: "", "uptime": 54661, "country_abbr": "T1"}
> ]}

/api/server/

Use: Gives you a list of information about the input list of servers. If you're authenticated, you will also be given each server's IP, Port, and the mppass you need to authenticate with the server. These servers may be either private or public.

Usage

Send a GET request to /api/server/ with the server hashes separated by commas, to get a json list of those servers.

< GET /api/server/700a2e3072c9d3b4fa34f5446f6845e8,nonexistentserverhash,a709fabdf836a2a102c952442bf2dab1

> { "servers" : [
>	{"hash": "700a2e3072c9d3b4fa34f5446f6845e8", "maxplayers": 20, "name": "Lava survival", "players": 0, "software": "MCDzienny", "uptime": 216392, "country_abbr": "US"},
>	{"hash": "a709fabdf836a2a102c952442bf2dab1", "maxplayers": 70, "name": "Freebuild server", "players": 5, "software": "MCGalaxy", "uptime": 185447, "country_abbr": "CA"},
> ]}

/server/heartbeat/

Use: Sends a server heartbeat request, and returns the URL of the server that can be used by clients to connect to the server.

Usage

Send a GET or POST request to /server/heartbeat/ (/heartbeat.jsp will also work) with the following parameters:

  • name - Name to display in the public servers list
  • port - Port number server is running on
  • users - Number of players currently on the server
  • max - Maxmium number of players that can play on the server
  • public - Whether the server appears on the public servers list
  • salt - Random string, used for generating mppasses
  • software - Optional. Name of the software running the server
  • web - Optional. Whether the server supports the web client 


< GET /server/heartbeat/ name=MyServer&port=25565&users=1&max=10&salt=472bm7&public=true

> http://www.classicube.net/server/play/abf74d16ae6df453f47265d8b47a3e1b/

If an error occurs

> {
>  "errors": [["Invalid salt."]], 
>  "response": "", 
>  "status": "fail"
> }
Errors
  • Server name is missing, or is longer than 64 characters.
  • Server salt is missing, or is longer than 256 characters.
  • More than the allowed number of servers per IP are sending heartbeats.
  • The server is listening on an IPv6 address. Only IPv4 listeners are supported.
  • The server is set as public, but the port is not open.

Web client

The web client wraps the connection in a WebSocket connection. The unpacked data is the same as the normal client.


https:// notes

When a user connects to a server via a https:// url, they actually connect to our websocket proxy, which in turn then connects to the server on their behalf over plain http.


Some notes about our websocket proxy:

  • The IP address of the proxy is always 34.223.5.250
  • The user's IP can be retrieved from the X-Real-IP header value