Difference between revisions of "Realms API"

From wiki.vg
Jump to navigation Jump to search
(Added temp. Pocket Realms API)
 
(12 intermediate revisions by 8 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.
+
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 Desktop Edition is located at https://mcoapi.minecraft.net .
+
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 documentated on [http://docs.mcperealms.apiary.io/ apiary], and will be moved here once it is completed.
+
There is also an endpoint for Pocket Edition in development, located at https://peoapi.minecraft.net. It is being documented at [[Pocket Realms]]
  
 
[[Category:Minecraft Modern]]
 
[[Category:Minecraft Modern]]
Line 9: Line 9:
 
== Sessions ==
 
== Sessions ==
 
Session identification is stored in a pair of cookies sent with the header of every request.
 
Session identification is stored in a pair of cookies sent with the header of every request.
sid is the session ID of the currently logged in user (see [[Authentication]])
+
The only required header within a request is having this cookie set.
user is the case-correct? username of the current user.
 
An example session is shown below:
 
<pre>
 
GET /mco/available HTTP/1.1
 
Cookie: sid=-000000000000000000;user=Herobrine
 
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
 
</pre>
 
  
 +
{| class="wikitable"
 +
! 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.
 +
|}
  
== Endpoints: ==
+
An example request:
=== GET /mco/available ===
+
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:
 +
{| class="wikitable"
 +
! 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.
 
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 : [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.
  
Parameters: none
+
Returns: String, if the client is outdated, it returns OUTDATED, if the client is running a snapshot, it returns OTHER, else it returns COMPATIBLE
  
Returns: plain text; only observed value is
+
==== GET /worlds ====
  false
+
 
 +
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.
 +
 
 +
{| class="wikitable"
 +
! 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:
 +
{| class="wikitable"
 +
! 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 /worlds ===
+
Get the download URL of the latest backup.
  
Return a list of servers that the user owns/is invited to?
+
Returns a json response like:
Returns: a JSON object with one array.
 
{"servers":[]}
 
  
=== GET /worlds/locations ===
+
{
 +
"downloadLink": "http://us-west-mcr-worlds.s3.amazonaws.com/dfasdfa/mcr_world.tar.gz?AWSAccessKeyId=ADSFASDFADSF&Expires=1457647137&Signature=ADSFASDFASDF",
 +
"resourcePackUrl": null,
 +
"resourcePackHash": null
 +
}
  
Returns a list of datacenters with server space available.
+
==== GET /ops/$ID ====
 +
Returns a list of operators for this server. You must own this server to view this.
  
Returns: a JSON object with currently available locations.
+
Returns:
  {"locations":[{"locationId":"3","locationName":"London"},{"locationId":"6","locationName":"Los Angeles - California"}],"suggestion":{"locationId":"3","locationName":"London"}}
+
  {| class="wikitable"
 +
! Key !! Value !! Value Type
 +
|-
 +
| ops || A array of player names || JSON array of Strings
 +
|}
  
=== GET /worlds/$ID ===
+
==== GET /subscriptions/$ID ====
 +
Returns the current life of a server subscription.
  
Gets world info? For example, worlds/1 returns:
+
Returns:
 +
{| class="wikitable"
 +
! 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
 +
|}
  
Not owner
+
==== GET /mco/buy ====
 +
Displays a status message to the user, along with a link to the Mojang website.
  
=== GET /worlds/$ID/join ===
+
Returns:
 +
{| class="wikitable"
 +
! 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
 +
|}
  
Joins a world?
+
==== GET /invites/count/pending ====
 +
Returns the amount of invites the player currently has waiting.
  
World '1' not found!
+
Returns: Integer value
  
=== POST /worlds/$NAME/$LOCATION ===
+
=== POST requests ===
  
Creates a world?
+
==== 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.

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

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.