Difference between revisions of "Realms API"
Bartle man (talk | contribs) |
|||
(9 intermediate revisions by 4 users not shown) | |||
Line 1: | Line 1: | ||
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 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:// | + | The API endpoint for the Desktop Edition is located at https://pc.realms.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:// | + | There is also an endpoint for Pocket Edition in development, located at https://pocket.realms.minecraft.net. It is being documented at [[Pocket Realms]] |
[[Category:Minecraft Modern]] | [[Category:Minecraft Modern]] | ||
Line 28: | Line 28: | ||
Pragma: no-cache | Pragma: no-cache | ||
User-Agent: Java/1.6.0_27 | User-Agent: Java/1.6.0_27 | ||
− | Host: | + | Host: pc.realms.minecraft.net |
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 | Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 | ||
Connection: keep-alive | Connection: keep-alive | ||
Line 43: | Line 43: | ||
|- | |- | ||
| remoteSubscriptionId || Unknown, perhaps linked to transaction? Seems to work if same as 'id' || String | | remoteSubscriptionId || Unknown, perhaps linked to transaction? Seems to work if same as 'id' || 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 | ||
+ | |- | ||
| name || The name of the server || String | | name || The name of the server || String | ||
|- | |- | ||
| motd || The MOTD of the server. Doesn't support color. || String | | motd || The MOTD of the server. Doesn't support color. || String | ||
+ | |- | ||
+ | | state || The status of the server. Can be one of the following: ADMIN_LOCK, CLOSED, OPEN, UNINITIALIZED || String | ||
+ | |- | ||
+ | | 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 |
|- | |- | ||
− | | | + | | worldType || Type of the world. Can be NORMAL, MINIGAME, ADVENTUREMAP, EXPERIENCE, INSPIRATION)|| 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 | ||
|- | |- | ||
− | | | + | | maxPlayers || The max players of the server, always returns '10' || Integer |
|- | |- | ||
− | | | + | | minigameName ||Name of minigame that is currently active. Returns `null` if not in a minigame || String |
|- | |- | ||
− | | | + | | 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 |
|- | |- | ||
− | | | + | | activeSlot || Current server world (1-4) || Integer |
− | |- | + | |- |
− | | | + | | slots || List of worlds slots. Only visible by owner (/worlds/$ID) || Unknown |
+ | |- | ||
+ | | member || Unknown || Boolean | ||
|} | |} | ||
Line 80: | Line 92: | ||
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 100: | Line 114: | ||
Example: | Example: | ||
− | {" | + | {"servers":[{ |
− | + | "id":1, | |
− | + | "remoteSubscriptionId":"aaaa0000bbbb1111cccc2222dddd3333", | |
− | + | "owner":"j_selby", | |
− | + | "ownerUUID":"3333dddd2222cccc1111bbbb0000aaaa", | |
− | + | "name":"A Test Server", | |
− | + | "motd":"This is a testing server!", | |
− | + | "state":"OPEN", | |
− | + | "daysLeft":30, | |
− | + | "expired":false, | |
− | + | "expiredTrial":false, | |
− | + | "worldType":"NORMAL", | |
− | + | "players":["Notch"], | |
+ | "maxPlayers":10, | ||
+ | "minigameName":null, | ||
+ | "minigameId":null, | ||
+ | "minigameImage":null, | ||
+ | "activeSlot":1, | ||
+ | "slots":null, | ||
+ | "member":false | ||
+ | }] | ||
+ | } | ||
==== GET /worlds/$ID ==== | ==== GET /worlds/$ID ==== | ||
Returns a single server listing about a server. | Returns a single server listing about a server. | ||
− | If | + | 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. | 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). | ||
Line 133: | Line 156: | ||
|- | |- | ||
| address || The address of a server, encoded as [IP]:[Port] || String | | address || The address of a server, encoded as [IP]:[Port] || String | ||
+ | |- | ||
+ | | pendingUpdate || If the server is waiting to update to a newer version || Boolean | ||
|} | |} | ||
Revision as of 13:29, 10 July 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://pc.realms.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://pocket.realms.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: pc.realms.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 |
---|---|---|
id | The ID of the server. Must be unique | Integer |
remoteSubscriptionId | Unknown, perhaps linked to transaction? Seems to work if same as 'id' | 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 |
name | The name of the server | String |
motd | The MOTD of the server. Doesn't support color. | String |
state | The status of the server. Can be one of the following: ADMIN_LOCK, CLOSED, OPEN, UNINITIALIZED | String |
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 |
worldType | Type of the world. Can be NORMAL, MINIGAME, ADVENTUREMAP, EXPERIENCE, INSPIRATION) | String |
players | A array of currently connected players? | JSON Array, with string values |
maxPlayers | The max players of the server, always returns '10' | Integer |
minigameName | Name of minigame that is currently active. Returns `null` if not in a minigame | String |
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 |
activeSlot | Current server world (1-4) | Integer |
slots | List of worlds slots. Only visible by owner (/worlds/$ID) | Unknown |
member | Unknown | Boolean |
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:
{"servers":[{ "id":1, "remoteSubscriptionId":"aaaa0000bbbb1111cccc2222dddd3333", "owner":"j_selby", "ownerUUID":"3333dddd2222cccc1111bbbb0000aaaa", "name":"A Test Server", "motd":"This is a testing server!", "state":"OPEN", "daysLeft":30, "expired":false, "expiredTrial":false, "worldType":"NORMAL", "players":["Notch"], "maxPlayers":10, "minigameName":null, "minigameId":null, "minigameImage":null, "activeSlot":1, "slots":null, "member":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.