Difference between revisions of "Realms API"
(Undo revision 13374 by Justgerrardz (talk) RVT spam) |
NathaanTFM (talk | contribs) (added warning) |
||
Line 1: | Line 1: | ||
+ | {{warning|This article is outdated}} | ||
+ | |||
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. | ||
Revision as of 15:56, 5 March 2018
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.