[ADMN/INFO] JSONAPI v4.3.0 - JSON HTTP and Socket API for controlling a server [1.4.7]

Alec Gorge · Mar 2, 2013

JSONAPI - Control your server and fetch information from your server.
Version: v4.3.0

JSONAPI is a plugin for Bukkit that allows you to access data and other information about your server and your players through a simple, yet secure, HTTP API. This allows you to make awesome websites, iPhone apps, and a way for your players to purchase goods online and automatically receive them in game.

However, this plugin won't do all of that by itself. It is simply an API that allows you to assemble the features in a way that makes sense for your needs.

Download
Download JSONAPI v4.3.0 (for Minecraft 1.4.*)
You can find the source code on GitHub at alecgorge/jsonapi. I accept pull requests!

What features exist in JSONAPI?

There are tons of API methods.
There are more than 146 different API methods in 8 different categories covering a wide range of features:

Chat (groups, prefixes, suffixes, etc.)

Economy (give money, create banks, etc.)

Permissions (control permissions and groups)

Edit signs and chests

Integration with drdanick's Remote Toolkit to enable the ability to turn the server on and off using API methods. Note: this requires the JSONAPI_RTK Remote Toolkit module.

Get a live stream of chat, connections and disconnections and/or the console.

...and many more standard features (ban, unban, inventory management, etc.)

JSONAPI is well documented.
There are many guides along with an expansive technical reference available on the wiki.
Every API method is documented and viewable online.

You can read a careful documentation of the the request and response format on the wiki if you are thinking about writing a new SDK or plan on rolling your own solution.

There are easy to use SDKs.
SDKs allow for easy usage of all of JSONAPI's capabilities currently there are 4 SDKs:

PHP: JSONAPI.php (docs)

.NET: JSONAPI

JavaScript: jsonapi.js

Python: MinecraftApi.py

Easily integrate JSONAPI with other plugins.
Using the API for JSONAPI, you can easily add new methods or stream sources. Check out the section "For plugin developers" at the bottom of the wiki.

There is an interactive test console.
Once you setup Adminium on your server, you can use this test console to easily test all of the available API methods and view the JSON response.

What else can you do with JSONAPI? You can...

Integrate your website and your Minecraft server

Control your server with your iPad/iPhone/iPod Touch through Adminium

Setup scripts that perform actions on your server, all through an easy to use API!

What uses JSONAPI?

Adminium

SpaceBukkit

HeroicDeath

SimpServ

Changelog:
just check github, i am getting tired of updating this

Version 3.6.0:

Economy features

Chat features

...much more

Version 3.3.2:

added world editing methods that deal with signs and chests

fixed the dreaded "java.lang.NoSuchFieldException: configuration" error and thus making JSONAPI dynmap .30+ compatible for real this time

Version 3.3.1:

fixed issues with lists not being trimmed

fixed the dreaded "java.lang.NoSuchFieldException: configuration" error and thus making JSONAPI dynmap .30+ compatible

Version 3.3.0:

fixed issues with Minecraft 1.1

added permission methods in the "permissions" namespace

added teleporting methods to teleport a player to a specific position

added appendToFile

updated upstream websocket deps

added getBukkitVersion

added getPluginVersion

added permission node jsonapi.calladmin for the /calladmin command

added a message that is sent to the player that used /calladmin once the notification is sent

fixed other misc. bugs I encountered

Version 3.2.1:

fixed issues with getPlayer

added getOfflinePlayer(String playerName)

Version 3.2.0:

added getOfflinePlayerNames

added getOfflinePlayers

added getPlayerNames

added getBlock

added setBlockData

added setBlockType

Version 3.1.1:

fixed an issue with the default configuration.

fixed cross platform issue with file i/o.

Version 3.1.0:

added addEnchantmentToPlayerInventorySlot

added addEnchantmentsToPlayerInventorySlot

added removeEnchantmentsFromPlayerInventorySlot

added setPlayerInventorySlotWithDataDamageAndEnchantments

added "level" and "experience" to player results

added enchantment information to player inventory output

Version 3.0.0:

added setPlayerFoodLevel

added setPlayerGameMode

added banWithReason

upgraded WebSocket server to support latest browsers

added setWorldTime

added the server-side component of push notifications for Adminium

added getSingleDirectory

modified getFileContents to read files as UTF-8

compatible with CraftBukkit for 1.0-1.0.1 (built against 1597)

added a CI site for you to grab the latest builds: http://ci.alecgorge.com/

Version 2.5.0:

added banWithReason api call

added new configuration option: bind-address. This can be used to only listen on a certain IP/hostname

fixed extra console output

added setPlayerGameMode api call.

updated to latest configuration api, bumped version to 2.5.0

updated world objects to include information about the weather

updated player objects to include information about food level, sprinting, exhaustion, gameMode

Version 2.4.0:

fix log-to-console

fix log-to-file

Version 2.3.1:

compiled against 1.8.1

fix memory usage being reported inaccurately

fix json having wrong mime type

Version 2.3:

compiled against 1.8

Version 2.2.2:

fix getStreamWithLimit

Version 2.2.1:

fix getPlayerCount

Version 2.2:

added configuration directive 'startup-delay' that allows you to configure how many milliseconds JSONAPI should wait before checking to see if dependent plugins exist

fixed some stuff that i don't remember

Version 2.1:

added getDirectory

fixed bug where config_rtk.yml wasn't being properly loaded

Version 2.0:

Massive behind the scenes update.

A few new APIs for other plugins were introduced:

An API for other plugins to register their own streams (example: HeroicDeathToJSONAPI)

An API for other plugins to read existing streams

An API for other plugins to handle/override API methods.

Thanks to suggestions @Xon there are a whole host of updates that make JSONAPI threadsafe. This improves stability.

added getStream

added getStreamWithLimit

Version 1.9:

fixed 2 random bytes being prepended to streams

added worldInfo to player object

other bug misc. bugs I found and fixed without telling anyone

Version 1.8.2:

compiled against CB 860

fixed (finally) that pesky problem with large streams

fixed race condition with concurrent stream logs

fixed console stream not showing JSONAPI log data

Version 1.8.1:

fixed streams not always providing new data

fixed .properties file being created when it doesn't exist

fixed other bug I have long since forgotten

Version 1.8:

fixed countless bugs, mostly the bug with broadcastWithName and HeroChat.

Version 1.7.2:

fixed output in return to console commands

Version 1.7.1:

fixed startup bugs that dealt with how files were checked

Version 1.7:

completed Remote Toolkit support (start, stop, restart; requires that JSONAPI_RTK be installed).

fixed JSONAPI to be compatible with CB 818

fixed lots of bugs

changed the configuration files to be 1 configuration file in yaml format (config.yml)

added a second configuration file (config_rtk.yml) for Remote Toolkit support.

Version 1.6.2:

added "setPlayerHealth"

added "setPlayerInventorySlotWithData"

added "setPlayerInventorySlotWithDataAndDamage"

added "getServer"

added Remote Toolkitmethods:

added "remotetoolkit.rescheduleServerRestart"

added "remotetoolkit.restartServer"

added "remotetoolkit.stopServer"

Version 1.6.1:

fixed the 1.6.1 milestone bugs.

Version 1.6:

added "isThunder" and "hasStorm" to the info returned by getWorlds()/getWorld(1)

added "broadcastWithName" to make chat as if you are actually on the server

fixed "clearPlayerInventorySlot" so it works with armor slots

added "getPluginFiles" to list all of the files in the plugin's data directory

added "isEnabled" to the info returned by getPlugin(1)/getPlugins()

added "updateInventorySlot" which allows you to change the number of items in an inventory slot without changing anything else

added a new streaming source "all", which behaves as if all the sources were subscribed tp

Version 1.5:

removed the JavaSysMon dependancy and removed the following API methods:

system.getCPUUsage

system.getSystemMemoryTotal

system.getSystemMemoryUsage

added getLatestConsoleLogsWithLimit

added getLatestChatsWithLimit

added getLatestConnectionsWithLimit

Version 1.4.1:

update the WebSocket server support the new HyBi-07 spec

Version 1.4:

added getLatestConsoleLogs

returns up to the last 50 lines in the console

added getLatestChats

returns up to the last 50 chat messages

added getLatestConnections

returns up to the last 50 connections/disconnections

added a WebSocket server that behaves just like the Socket server, except it uses the WebSocket protocol (obviously) and runs on port that you set in the settings plus 2. (default is 20061).

changed runConsoleCommand to actually send commands to the console

Version 1.3.1:

fixed some stability issues with streams

Version 1.3

added the system namespace for CPU, disk and memory information

added method whitelist allowing you to define certain methods that can be used without proper authentication (JSONAPIMethodNoAuthWhitelist.txt).

added two console-onlycommands:

reloadjsonapi: self explanatory, just restarts all the JSONAPI servers and reloads all the methods from the JSON files.

jsonapi-list: lists all the of the currently loaded namespaces and methods

added getServerPort and getServerIp

made setPlayerInventorySlot and setPlayerInventorySlotWithDamage play nice with armor. Just use the slot numbers as defined in this picture.

added a super handy testing environment: http://alecgorge.github.com/jsonapi/ . This testbed is 100% client side and is never stored anywhere (except in memory of course). You can view the source code at: https://github.com/alecgorge/jsonapi/tree/gh-pages

probably more stuff that I forgot about...

Version 1.2

added setPlayerInventorySlotWithDamage

added clearPlayerInventorySlot

fixed setPlayerInventorySlot so that you can set slots to air without crashing the client

fixed a bug with the method that tested for API method existence.

Version 1.1

added getPlayerCount

added givePlayerItemWithData

added givePlayerItemDropWithData

added reloadjsonapi console command

added the console stream.

Version 1.0

Initial release.

Donate

I have spent well over 300 hours developing and testing JSONAPI I would really appreciate it if you would donate some money to say thanks. If you want, I can add you (with a link to a server or community) as a donor on this post when you donate.

Donors

EmuCraft - The fun, friendly, Australian minecraft community.

Anticraft - Don't craft, create.

Big thanks to rch for helping me bug test!

Alec Gorge · May 28, 2011

That happened to me once, but I restarted the server and it stopped happening. It has never happened again for me.

See if you can replicate it.

PVPcTutorials · May 31, 2011

Anytime I call a method I get an error like:
Code:
17:52:02 [INFO] [JSONAPI] [API Call] 127.0.0.1: method=player.getPlayers?args=[]
17:52:02 [WARNING] [JSONAPI] The method 'player.getPlayers' does not exist!
What am I doing wrong?

Alec Gorge · May 31, 2011

player.getPlayers does not exist, that is why.

API methods are available here: http://ramblingwood.com/minecraft/jsonapi/apidocs/

PVPcTutorials · May 31, 2011

I'm only getting this error through VisualBasic.
My code there

Code:

#Init works.
    Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click
        Me.Text = json.net.player.getPlayers().ToArray.ToString
    End Sub

PVPcTutorials · May 31, 2011

Alec Gorge said: ↑

player.getPlayers does not exist, that is why.

API methods are available here: http://ramblingwood.com/minecraft/jsonapi/apidocs/

Ok, but why says the .Net dll it's valid?

PVPcTutorials · May 31, 2011

Another question: Why says PHP:
Code:
Fatal error: Call to undefined function curl_init() in [Path]\JSONAPI.php on line 94
?

xPaw · May 31, 2011

PVPcTutorials said: ↑
Another question: Why says PHP:
Code:
Fatal error: Call to undefined function curl_init() in [Path]\JSONAPI.php on line 94
?
You need cURL extension for it to work.

Alec Gorge · May 31, 2011

.net dll has no knowledge of what methods actually exists because the person who runs the server can change them.

Also xPaw is correct.

Accalia de Elementia · Jun 2, 2011

Excellent plugin, Excellent documentation.

+ 1 internets to you sir.

I have just one bad thing to report, but i also have a good thing to report too.

The bad:
getServerIP always returns an empty string for me when calling it.

Server: Debian Lenny VPS
CraftBukkit: b818
JSONAPI: version 1.6.2 (jar MD5: f8b7887f0693f70b5e9f2587df3b6dd7)

The good:
I whipped up a python wrapper for your API. It is based heavily on your PHP wrapper with a few differences

It uses the stream protocol in order to keep connections down (does not block between reading results of commands)

It uses dynamic method generation to duplicate remote server methods (*including* custom defined ones!) [to call getWorlds you can say api.call('getWorlds', []) *OR* api.getWorlds()]

Probably more that I've forgotten

It is still very lightly tested but if you want to give it a try be my guest. Depends only on python 2.7.x (may work with older, untested)
http://pastebin.com/UEVDjBtr

Comments/ suggestions appreciated, and thanks for making such a great plugin!

Alec Gorge · Jun 2, 2011

Many thanks! I am glad you find the documentation useful, because it took forever to document everything !

getServerIP returns whatever you have in your server.properties file--which is usually an empty string.

That is a fantastic good! It is good to see usage of the stream API! I like the dynamic invocation idea, very clever!

I have gone ahead and added it to the list of SDKs on the OP and put it in the GitHub repo. If you have changes that need to be made to the python SDK, just send a pull request.

EDIT: JSONAPI 1.7 will be out very soon and support MC 1.6.6 completely (only broadcastWithName is broken in MC 1.6.6), along with Remote Toolkit support for starting (unholding), stopping (holding) and restarting the Minecraft server.

Accalia de Elementia · Jun 2, 2011

Hmm... Now i'll have to learn GIT... sound interesting!

My PHP's rather rusty (about 7 years gone i think) but I'd be glad to try to whip up something to dynamically add those functions to your PHP class. I'll give that a go once i finish getting the Python version worked out if you'd like, or you can probably figure it out on your own based on what i'm doing for Python if you prefer.

Alec Gorge · Jun 2, 2011

Oh I know how to do it, it just didn't because it is easier to document the traditional way. You just need to use the __call magic method.

You don't actually have to learn git. You can make a github account, then fork my repo and then use githubs built in editor to change the file and then commit it. You can then send me a pull request.

Just work out whatever you need to work out for the Python one.

Accalia de Elementia · Jun 2, 2011

"Aww, but Alec... we *wanted* to learn GIT!" ;-)

It would be easier to document without the dynamic methods, that is true. I settled for having the dynamic methods and generating the correct docstrings for them based on the JSON method definitions. It only works for instantiated objects but with the Python interpreter always lying around it's easy enough check if I forget.

I'll do that. While i'm at it shall I nerf the django website i'm building this wrapper for so that you can include it as a sample usage of the SDK?

Alec Gorge · Jun 2, 2011

Well I won't stop you

Ah I see.

Sure, that would be great!

Accalia de Elementia · Jun 2, 2011

Great! It shouldn't take me too long to get everything firmed up/properly documented and the website nerf'd.... unless i get sucked into playing minecraft and not coding for it.....

Alec Gorge · Jun 2, 2011

Haha, like that would ever happen

Good luck!

iffa · Jun 2, 2011

I've spent days trying to figure out how to actually use this with PHP "correctly". lol

KeNNy_aKa_MaX · Jun 2, 2011

Hello, im using the API with PHP, and i've got a question, i send a call for getLatestChatsWithLimit and pass it a parameter of 20, i expect it to return last 20 messages on the server, instead, it returns me the first 20 messages of the server, and i have no idea how to get the last ones...
This is a part of the code im using:

PHP:

$chat = $api->call("getLatestChatsWithLimit", array('20')); $i = 1; while($info = $chat['success'][$i-1]) { $chatMessages .= '[' . date("H:i:s", $info['time']) . '] ' . $info['player'] . ': ' . $info['message'] . '<br />'; $i++; } echo $chatMessages;

Edit #1:
Here's a pic: -link-

Edit #2:
Its 1.6.6

Edit #3:
getLatestChats runs ok and returns correctly the last 50 messages.

Alec Gorge · Jun 3, 2011

@KeNNy_aKa_MaX That is a bug. It is fixed in the new version that is just being released right now.

Version 1.7 released!

completed Remote Toolkit support (start, stop, restart; requires that JSONAPI_RTK be installed).

fixed JSONAPI to be compatible with CB 818

fixed lots of bugs

changed the configuration files to be 1 configuration file in yaml format (config.yml)

added a second configuration file (config_rtk.yml) for Remote Toolkit support.

Xon · Jun 3, 2011

When trying to install this plugin (extracting the jar + folder) I get the following error;
Code:
20:04:35 [SEVERE] [JSONAPI] Couldn't start server!
20:04:35 [SEVERE] java.io.IOException: Access is denied
20:04:35 [SEVERE]       at java.io.WinNTFileSystem.createFileExclusively(NativeMethod)
20:04:35 [SEVERE]       at java.io.File.createNewFile(Unknown Source)
20:04:35 [SEVERE]       at com.ramblingwood.minecraft.jsonapi.JSONAPI.onEnable(JSONAPI.java:102)
Looking at the sourcecode
if(getDataFolder().exists()) {
getDataFolder().createNewFile();
}
The if condition is inverted, it always attempts to create the data folder if it exists. Which throws an exception, and the code crashes if the folder doesn't exist.

Whalum · Jun 4, 2011

Am I the only one who can't get runConsoleCommand and broadcast working in 1.7? They won't work with the testing console or with my own code. All I get is this in the Minecraft console:
Code:
22:13:15 [INFO] [JSONAPI] [API Call] 127.0.0.1: method=runConsoleCommand?args=["help"]
But the command doesn't get executed.

Both work fine with JSONAPI 1.6.2.

Alec Gorge · Jun 4, 2011

@Xon Thanks, I fixed that in the new version. Make sure you copy the data folder though, it has vital files.

@Whalum Good point, I just fixed that. Download v1.7.2, it should output like you expect.

Whalum · Jun 4, 2011

Thank you for the quick fix - and for the excellent plugin, of course!

Crimsonfox · Jun 4, 2011

Does the test page (http://alecgorge.github.com/jsonapi/) read your custom methods or is it strictly the default ones?

Alec Gorge · Jun 4, 2011

It is simply the default ones. I want to add support for custom methods so look for that in the near future.

Crimsonfox · Jun 4, 2011

Alec Gorge said: ↑

It is simply the default ones. I want to add support for custom methods so look for that in the near future.

Thanks for the quick reply! I'm just looking through the PHP class now and it looks very promising, I think this is exactly what I'm looking for. =)

Edit: One last thing, to figure out other plugins correct calls would I be right in saying they're effectively the same as the permissions nodes or is it completely separate altogether.

Xon · Jun 5, 2011

Alec Gorge said: ↑

@Xon Thanks, I fixed that in the new version. Make sure you copy the data folder though, it has vital files.

Thanks for the quick fix, and I have copied the data folder over.

Looking at the data returned by getPlayers(), there doesn't appear to be any way to easily get the world that the player is on.

Is it possible to define something like the following in the methods.json files?
Code:
		{
			"name": "getWeatherDuration",
			"desc": "Get the remaining time in ticks of the current conditions for a World.",
			"returns": ["int", "Time in ticks"],
			"call": "Server.getWorld(0).getWeatherDuration()"
		},

Crimsonfox · Jun 5, 2011

Arg, can't see to get the right format for a call with an argument from PHP it's just returning "NULL". Trying to use broadcast. I thought it was like this:
Code:
require('lib/JSONAPI.php'); // get this file at: https://github.com/alecgorge/jsonapi/raw/master/sdk/php/JSONAPI.php

$api = new JSONAPI("*****", 20061, "****", "****", "****");
$array = array();
$array[0] = "test";
var_dump($api->call("broadcast",$array));
Obviously not I guess.

Alec Gorge · Jun 5, 2011

It is working that method always returns null, even on success.

Crimsonfox · Jun 5, 2011

Alec Gorge said: ↑

It is working that method always returns null, even on success.

Ah, well I'm not getting any output in-game. If I change the port to 20059 I get "You're not allowed to make API calls" =/

I could have the IP wrong potentially, is there a way of allowing all IP's in the white list like using an "any" tag?

Log in or Sign up

[ADMN/INFO] JSONAPI v4.3.0 - JSON HTTP and Socket API for controlling a server [1.4.7]

Alec Gorge

Alec Gorge

PVPcTutorials

Alec Gorge

PVPcTutorials

PVPcTutorials

PVPcTutorials

xPaw

Alec Gorge

Accalia de Elementia

Alec Gorge

Accalia de Elementia

Alec Gorge

Accalia de Elementia

Alec Gorge

Accalia de Elementia

Alec Gorge

iffa

KeNNy_aKa_MaX

Alec Gorge

Xon

Whalum

Alec Gorge

Whalum

Crimsonfox

Alec Gorge

Crimsonfox

Xon

Crimsonfox

Alec Gorge

Crimsonfox

Share This Page

[ADMN/INFO] JSONAPI v4.3.0 - JSON HTTP and Socket API for controlling a server [1.4.7]

Share This Page

Useful Searches