Difference between revisions of "Realms API"
NathaanTFM (talk | contribs) |
NathaanTFM (talk | contribs) |
||
Line 40: | Line 40: | ||
! Key !! Value !! Value Type | ! Key !! Value !! Value Type | ||
|- | |- | ||
− | | activeSlot || | + | | activeSlot || Current server world (1-4) || Integer |
|- | |- | ||
| daysLeft || How many days are left of subscription. Always returns '0' if not owner and returns '-1' if expired || Integer | | daysLeft || How many days are left of subscription. Always returns '0' if not owner and returns '-1' if expired || Integer | ||
Line 51: | Line 51: | ||
|- | |- | ||
| maxPlayers || The max players of the server, always returns '10' || Integer | | maxPlayers || The max players of the server, always returns '10' || Integer | ||
− | |||
− | |||
|- | |- | ||
| minigameId ||Not confirmed, probably unique Id of Minigame map. Returns `null` if not in a minigame || Integer | | minigameId ||Not confirmed, probably unique Id of Minigame map. Returns `null` if not in a minigame || Integer | ||
|- | |- | ||
− | | minigameImage || | + | | minigameImage ||base64 of the current minigame image in format PNG. Returns `null` if not in a minigame || String |
|- | |- | ||
− | | minigameName || | + | | minigameName ||Name of minigame that is currently active. Returns `null` if not in a minigame || String |
|- | |- | ||
| motd || The MOTD of the server. Doesn't support color. || String | | motd || The MOTD of the server. Doesn't support color. || String | ||
Line 64: | Line 62: | ||
| name || The name of the server || String | | name || The name of the server || String | ||
|- | |- | ||
− | | owner || The owner of the server | + | | owner || The owner of the server. || String |
|- | |- | ||
− | | ownerUUID || The unique ID of the owner || String | + | | ownerUUID || The unique ID of the owner. If this is equal to the previewing players unique ID, the configure button will be accessible. Note that the UUID haven't got hyphens|| String |
|- | |- | ||
| players || A array of currently connected players? || JSON Array, with string values | | players || A array of currently connected players? || JSON Array, with string values | ||
Line 76: | Line 74: | ||
| state || The status of the server. Can be one of the following: ADMIN_LOCK, CLOSED, OPEN, UNINITIALIZED || String | | state || The status of the server. Can be one of the following: ADMIN_LOCK, CLOSED, OPEN, UNINITIALIZED || String | ||
|- | |- | ||
− | | worldType || | + | | worldType || Type of the world. Can be NORMAL, MINIGAME, ADVENTUREMAP, EXPERIENCE, INSPIRATION)|| String |
|- | |- | ||
|} | |} | ||
Line 93: | Line 91: | ||
Prior to Realms release, this returned false. | Prior to Realms release, this returned false. | ||
− | ==== GET /mco/client/ | + | If it returns false, this screen appears : [http://prntscr.com/ewxutq]. |
+ | |||
+ | ==== GET /mco/client/compatible ==== | ||
Returns whether the clients version is up to date with Realms. This is checked against the Cookie token. | Returns whether the clients version is up to date with Realms. This is checked against the Cookie token. | ||
− | Returns: | + | Returns: String, if the client is outdated, it returns OUTDATED, if the client is running a snapshot, it returns OTHER, else it returns COMPATIBLE |
==== GET /worlds ==== | ==== GET /worlds ==== | ||
Line 134: | Line 134: | ||
Returns: a JSON encoded Server, as above. | Returns: a JSON encoded Server, as above. | ||
− | ==== GET /worlds/$ID/join ==== | + | ==== GET /worlds/v1/$ID/join/pc ==== |
Requires TOS to be agreed to (as below). | Requires TOS to be agreed to (as below). | ||
Revision as of 23:39, 15 April 2017
The Minecraft Realms API is the API endpoint used to control worlds hosted by Mojang's Minecraft Realms service. This is a paid service provided to abstract managing a Minecraft server. More information on this can be found at https://minecraft.net/realms.
The API endpoint for the Desktop Edition is located at https://mcoapi.minecraft.net. This is where all requests, as listed on this page, should be sent to.
There is also an endpoint for Pocket Edition in development, located at https://peoapi.minecraft.net. It is being documented at Pocket Realms
Contents
- 1 Sessions
- 2 Notes
- 3 Defining a server
- 4 Endpoints
- 4.1 GET requests
- 4.1.1 GET /mco/available
- 4.1.2 GET /mco/client/compatible
- 4.1.3 GET /worlds
- 4.1.4 GET /worlds/$ID
- 4.1.5 GET /worlds/v1/$ID/join/pc
- 4.1.6 GET /worlds/$ID/backups
- 4.1.7 GET /worlds/$ID/slot/$WORLD(1-4)/download
- 4.1.8 GET /ops/$ID
- 4.1.9 GET /subscriptions/$ID
- 4.1.10 GET /mco/buy
- 4.1.11 GET /invites/count/pending
- 4.2 POST requests
- 4.1 GET requests
Sessions
Session identification is stored in a pair of cookies sent with the header of every request. The only required header within a request is having this cookie set.
Key | Value |
---|---|
sid | This is the current session ID of the logged in user. This follows the format of:
token:<accessToken>:<player UUID> |
user | This is the username of the logged in user. This value is case sensitive. |
version | The version of the Minecraft instance running. |
An example request:
GET /mco/available HTTP/1.1 Cookie: sid=<token>;user=Herobrine;version=1.7.9 Cache-Control: no-cache Pragma: no-cache User-Agent: Java/1.6.0_27 Host: mcoapi.minecraft.net Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Connection: keep-alive
Notes
As per standard HTTP, a GET request has no parameters, and a POST request can potentially contain content (Note, several POST requests below has empty content).
Defining a server
For most endpoints requiring a server, it is returned in a JSON object format, containing the following values:
Key | Value | Value Type |
---|---|---|
activeSlot | Current server world (1-4) | Integer |
daysLeft | How many days are left of subscription. Always returns '0' if not owner and returns '-1' if expired | Integer |
expired | Whether the subscription has expired | Boolean |
expiredTrial | Whether the trial subscription has expired | Boolean |
id | The ID of the server. Must be unique | Integer |
maxPlayers | The max players of the server, always returns '10' | Integer |
minigameId | Not confirmed, probably unique Id of Minigame map. Returns `null` if not in a minigame | Integer |
minigameImage | base64 of the current minigame image in format PNG. Returns `null` if not in a minigame | String |
minigameName | Name of minigame that is currently active. Returns `null` if not in a minigame | String |
motd | The MOTD of the server. Doesn't support color. | String |
name | The name of the server | String |
owner | The owner of the server. | String |
ownerUUID | The unique ID of the owner. If this is equal to the previewing players unique ID, the configure button will be accessible. Note that the UUID haven't got hyphens | String |
players | A array of currently connected players? | JSON Array, with string values |
remoteSubscriptionId | Unknown, perhaps linked to transaction? Seems to work if same as 'id' | String |
slots | List of worlds slots. Only visible by owner (/worlds/$ID) | Unknown |
state | The status of the server. Can be one of the following: ADMIN_LOCK, CLOSED, OPEN, UNINITIALIZED | String |
worldType | Type of the world. Can be NORMAL, MINIGAME, ADVENTUREMAP, EXPERIENCE, INSPIRATION) | String |
Endpoints
GET requests
GET /mco/available
Returns whether the user can access the Minecraft Realms service. This request does not require a Cookie token to be sent.
Returns: plain text; only observed value is
true
Prior to Realms release, this returned false.
If it returns false, this screen appears : [1].
GET /mco/client/compatible
Returns whether the clients version is up to date with Realms. This is checked against the Cookie token.
Returns: String, if the client is outdated, it returns OUTDATED, if the client is running a snapshot, it returns OTHER, else it returns COMPATIBLE
GET /worlds
Return a list of servers that the user is invited to or owns.
Returns: a JSON object with one array. Each element within the array represents a server.
Key | Value | Value Type |
---|---|---|
servers | A array of servers | JSON array of Servers |
Example:
{"worlds": [ {"id": 1, "remoteSubscriptionId": "1", "name": "A Test Server", "players": ["Notch"], "motd": "This is a testing server!", "state": "OPEN", "owner": "j_selby", "daysLeft": 30, "ip": "localhost:25565", "expired": false, "minigame": false}, ... ]}
GET /worlds/$ID
Returns a single server listing about a server. If you are not the owner of the server, the server will return a 403 error, with a JSON encoded error message.
Returns: a JSON encoded Server, as above.
GET /worlds/v1/$ID/join/pc
Requires TOS to be agreed to (as below).
Used to get the IP address for a server.
If a server doesn't exist/you do not have currently have access to it, the server will return a 404 error, with no content.
Returns:
Key | Value | Value Type |
---|---|---|
address | The address of a server, encoded as [IP]:[Port] | String |
pendingUpdate | If the server is waiting to update to a newer version | Boolean |
GET /worlds/$ID/backups
Returns a list of backups for the world.
If a server doesn't exist/you do not have currently have access to it, the server will return a 403 error, with no content.
Returns: a JSON encoded list of backups for the specified world ID
GET /worlds/$ID/slot/$WORLD(1-4)/download
Get the download URL of the latest backup.
Returns a json response like:
{ "downloadLink": "http://us-west-mcr-worlds.s3.amazonaws.com/dfasdfa/mcr_world.tar.gz?AWSAccessKeyId=ADSFASDFADSF&Expires=1457647137&Signature=ADSFASDFASDF", "resourcePackUrl": null, "resourcePackHash": null }
GET /ops/$ID
Returns a list of operators for this server. You must own this server to view this.
Returns:
Key | Value | Value Type |
---|---|---|
ops | A array of player names | JSON array of Strings |
GET /subscriptions/$ID
Returns the current life of a server subscription.
Returns:
Key | Value | Value Type |
---|---|---|
startDate | A millisecond value. This is measured from January 1, 1970. | Long |
daysLeft | The amount of days left within this subscription | Integer |
subscriptionType | The kind of subscription this user has. This has been seen to be NORMAL or RECURRING. | String |
GET /mco/buy
Displays a status message to the user, along with a link to the Mojang website.
Returns:
Key | Value | Value Type |
---|---|---|
statusMessage | The message displayed to the user | String |
buyLink | A URL to the purchase website. Optional. If not provided, no link is shown | String |
GET /invites/count/pending
Returns the amount of invites the player currently has waiting.
Returns: Integer value
POST requests
POST /mco/tos/agreed
To join Realms servers, you must agree to the TOS. Sending a blank POST request to this endpoint will set this flag.