Analyzing the jsonapi request and response format

#Analyzing the JSONAPI request and response format This is for people interested in how the JSONAPI API request and response format works. If you are interested in a guide on how to use the API please look at the guides section on the Home page of the wiki.

##Key format All request need to be authenticated with a key. The format for this key, as done in PHP is:

hash('sha256', $username . $methodNameOrSourceName . $password . $salt);

Here is is in Java (this assumes you have a method called sha256 that creates the SHA256 hash from a String):

sha256(username + methodNameOrSourceName + password + salt);

In both cases:

• username needs to be a valid username that is in the server's JSONAPIAuthentication.txt in the plugins/JSONAPI/ folder.
• methodNameOrSourceName is the name of the method that you are trying to call. It can also be the name of the data source you are trying to subscribe to in the stream API.
• password is the corresponding password to username.
• salt is the salt set in the server's JSONAPI.properties in the plugins/JSONAPI folder.

This format means that there is a different key for each different API method.

When you have multiple username and password combinations, that means that there can be more than one valid key.

##Requests All requests for JSONAPI fall into one of four categories. These categories are:

• A standard API request
• A multiple API request
• A stream API request
• An invalid request

###Standard API request A standard API request is one where a request is made for data, and the data is immediately returned. Examples of standard API methods are getPlayerLimit and getServerVersion.

A standard API request looks like this:

/api/call?method={methodName}&args={jsonEncodedArrayOfArgs}&key={key}

Every thing in curly braces in that URL is something you will need to change for each different API request. Let's analyze each one:

• {methodName} is the the name of the API method you wish to call. There is a list of the default ones built into JSONAPI are available at this page. Some examples values are getPlayerLimit, getPlayer or dynmap.getPort.
• {jsonEncodedArrayOfArgs} is a JSON encoded array of arguments for a particular method. Every argument listed on the method API docs is required. It is recommended to pass an empty array when there are no arguments. However, not utilizing the args GET variable is also acceptable. Do not forget encode the JSON encoded result in accordance with RFC 3986. In PHP the rawurlencode function satisfies this. In JavaScript the escape() function seems to satisfy this.
• {key} is a valid key for this method. (see above for more information on keys).

You can use standard API requests in both a HTTP request and an open socket connection. See How to use the standard API over HTTP and How to use the standard API over a socket connection for more information.

###Multiple API request Exactly the same as a standard API request, but method is a JSON-encoded array of method names and args is a JSON-encoded array of arrays. Don't forget properly encoded both.

###Stream API request A stream API request is one where a request is made to "subscribe" to a particular data source, and as new data is found on the server, another response line is sent back to the client.

A stream API request looks like this:

/api/subscribe?source={sourceName}&key={key}

Every thing in curly braces in that URL is something you will need to change for each different API request. Let's analyze each one:

• {sourceName} is the the name the data source you want to subscribe to. The only options right now are chat, console and connections.
• {key} is a valid key for this method. (see above for more information on keys).

You can use stream API requests in both a HTTP request and an open socket connection. See How to use the stream API over HTTP and How to use the stream API over a socket connection for more information.

###An invalid request An invalid request does not fulfill any of the other request types.