[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!

NotoriousPyro · May 12, 2011

@Alec Gorge, not sure if it's a bug mate but memory usage doesn't seem to change all that much for me. McMyAdmin reports a different memory usage too.

xPaw · May 12, 2011

NotoriousPyro said: ↑

@Alec Gorge, not sure if it's a bug mate but memory usage doesn't seem to change all that much for me. McMyAdmin reports a different memory usage too.

That was bothering me too ..

Alec Gorge · May 14, 2011

@NotoriousPyro @xPaw I don't know what to tell you about the memory thing. It has always been perfectly accurate for me.

In other news:

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

xPaw · May 14, 2011

Will getCPUUsage come back?

And those "withLimit" you could do without adding new methods, by just giving paramater for def. method and make it 50 by default if nothing was passed

NotoriousPyro · May 14, 2011

xPaw said: ↑

Will those methods come back?

And those "withLimit" you could do without adding new methods, by just giving paramater for def. method and make it 50 by default if nothing was passed

Agreed, it should be without adding new API calls.

@Alec Gorge, it's probably right. It's just a little different than what I'm used to seeing compared to system usage

Alec Gorge · May 14, 2011

getCPUUsage will not come back. There is no way to do it reliably.

Unfortunately due to the way that I have JSONAPI setup you cannot have two methods with the same name. I could change this, but this was partially by design to make it clear what was supposed to happen so that you could look at your API calls a few months from now and know what they mean.

NotoriousPyro · May 14, 2011

Alec Gorge said: ↑

getCPUUsage will not come back. There is no way to do it reliably.

Unfortunately due to the way that I have JSONAPI setup you cannot have two methods with the same name. I could change this, but this was partially by design to make it clear what was supposed to happen so that you could look at your API calls a few months from now and know what they mean.

What we mean is have the same API call, but if there is nothing specified as to how much to return then just return 50.

Simple if statement

You could program your own way to monitor CPU usage but you'd need to do it for both *nix and Windows systems - which would make the plugin unnecessarily big.

Alec Gorge · May 14, 2011

I know what you mean, but it is not a simple if statement.

JSONAPI is designed so that NO API methods are defined in Java and are instead defined in JSON files. I define the name of an API method, and then a specify how many arguments and of what type they are. This is so that I can convert from an int to a float or a float to a double or whatever transparently.

I store all the methods in a hashtable like this: namespace => hashtable(methodname => methodObject).

A different number of arguments will simply cause the method to be overridden.

Besides, I like the verbosity. It makes things much clearer and eliminates annoying bugs.

tl;dr You cannot do method overloading in a loosely typed environment.

NotoriousPyro · May 14, 2011

@Alec Gorge, ah I see. No worries then

tha d0ctor · May 15, 2011

would it be possible to link this to a link on your own website so that everytime someone clicked on a certain add on a webpage you could tie a minecraft ingame command to it like /money grant etc? if the user is signed in?

xPaw · May 15, 2011

Could you add new method?

updatePlayerInventorySlot ( player, slotNumber, newAmount )

and if there is any block/item in that slot, it will update amount of it.

NotoriousPyro · May 16, 2011

@Alec Gorge, there seems to be a problem with JSONAPI.php.

When a player has a name that starts with a zero, the zero is removed and thus the API call fails. I've narrowed it down to the part which converts variables to floats.

I've had to comment those areas out.

PHP:

public function call($method, array $args = array()) { if(is_array($method)) { $this->callMultiple($method, $args); } /*foreach((array)$args as $k => $v) { if(is_numeric($v)) { $args[$k] = (float)$v; } }*/ $url = $this->makeURL($method, $args); return json_decode($this->curl($url), true); } private function curl($url) { $c = curl_init($url); curl_setopt($c, CURLOPT_PORT, $this->port); curl_setopt($c, CURLOPT_HEADER, false); curl_setopt($c, CURLOPT_RETURNTRANSFER, true); $result = curl_exec($c); curl_close($c); return $result; } /** * Calls the given JSONAPI API methods with the given args. * * @param array $methods An array strings, where each string is the name of a JSONAPI API method to call. * @param array $args An array of arrays of arguments that are to be passed. * @throws Exception When the length of the $methods array and the $args array are different, an exception is thrown. * @return array An array of associative arrays representing the JSON that was returned. */ public function callMultiple(array $methods, array $args = array()) { if(count($methods) !== count($args)) { throw new Exception("The length of the arrays \$methods and \$args are different! You need an array of arguments for each method!"); } /*foreach((array)$args as $key => $v) { foreach((array)$v as $k => $x) { if(is_numeric($x)) { $args[$key][$k] = (float)$x; } } }*/ $url = $this->makeURLMultiple($methods, $args); return json_decode($this->curl($url), true); }

Emirin · May 16, 2011

Thank god Alec, I've been tired of updating the last version you left me with for mineadmin >_<

Can I get you on Gmail or something so we can work together on some things?

Alec Gorge · May 16, 2011

@xPaw I will put that in the next release if you open it as an issue in the issue tracker.
@NotoriousPyro Huh. That isn't useful. I'll remove that "feature".
@Emirin Yeah. I sent a PM thingy.

Emirin · May 17, 2011

Alec did you forget to add back in getInventory for players? I don't see an equivelent in your documentation or in APIWrapperMethods.java.

Also I don't see a status for the state of the plugins returned in getPlugins() or getPlugin()

Alec Gorge · May 17, 2011

http://ramblingwood.com/minecraft/jsonapi/apidocs/#Server.getPlayer(0)

That gets you the inventory.

ark3typ3 · May 18, 2011

Hmmm, I keep getting this message

15:20:04 [INFO] [JSONAPI] [API Call] 10.0.0.2: Invalid API Key.

I've double checked my information and it still seems to do that...

*This is using the test thingy on your site

*EDIT: NVM, I had changed my authentication and didn't reload apparently...

Alec Gorge · May 19, 2011

@ark3typ3 I'm glad you figured that out. Did you just forget to reload the plugin? My plugin doesn't reload config every time the file changes.

slizone · May 19, 2011

It would be nice if someone can post a VB.net or C# example for this API.
Or if someone creates a .NET Library.

Greetings
slizone

Alec Gorge · May 19, 2011

I'll make a .NET library. That sounds like fun.

slizone · May 19, 2011

Thank you ;D I have a problem with the json encryption stuff

paulstraw · May 20, 2011

I'm having trouble with the WebSocket server; it never seems to connect or error out. Here's the code I'm using (JS):
Code:
var chatSocket = new WebSocket('ws://server:20061/api/subscribe?source=chat&key=blahblah');

chatSocket.onmessage = function(e) {
    console.log(e);
};

//onerror, onopen, and onclose never do anything, either
The readyState never changes or anything. Am I doing something wrong, or just missing something, or what?

Alec Gorge · May 20, 2011

The first argument to WebSocket is "ws://server:20061/"

After you connect you send a message that says "/api/subscribe?source=chat&key=blahblah".

slizone · May 20, 2011

@Alec Gorge
if you need help with the .NET Library, i can help you

paulstraw · May 20, 2011

Ah, okay. Still no luck, though. From what I'm seeing, it looks like no browsers in the wild actually support HyBi-07 yet. What are you using to test with? (No luck here with Chrome 11.0.696.68, Safari 5.1, or Mobile Safari on iOS 4.3.3)

ark3typ3 · May 21, 2011

Alec Gorge said: ↑

@ark3typ3 I'm glad you figured that out. Did you just forget to reload the plugin? My plugin doesn't reload config every time the file changes.

Yup, t'was the issue

Alec Gorge · May 22, 2011

@paulstraw I think there was a flaw in the WebSocket server. Download 1.6 and try again. HyBi support was removed. It works in Chrome 11 for sure.

@slizone The .NET library is up. The DLL in that directory is for .NET 3.5 and includes all deps (thanks to ilmerge), but it will probably work with 2.0+. There is a sample project in the sample folder. If you customize the JSONAPI project, just remember to reference JsonExSerializer.dll in the SDK/JSONAPI folder.

@NotoriousPyro I have added "broadcastWithName" which does what you had wanted before. Check it out on the API docs.

Version 1.6 released:

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

paulstraw · May 22, 2011

Working beautifully now, thanks so much! (The "all" streaming source is awesome, by the way)

EDIT:
It seems after around 30ish disconnects/reconnects, the WS server stops streaming messages. It'll send the initial payload, then not send any new events unless you disconnect/reconnect again. Any thoughts?

slizone · May 22, 2011

Really good work Alec!
Thank you

xPaw · May 22, 2011

Good job as always

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

NotoriousPyro

xPaw

Alec Gorge

xPaw

NotoriousPyro

Alec Gorge

NotoriousPyro

Alec Gorge

NotoriousPyro

tha d0ctor

xPaw

NotoriousPyro

Emirin

Alec Gorge

Emirin

Alec Gorge

ark3typ3

Alec Gorge

slizone

Alec Gorge

slizone

paulstraw

Alec Gorge

slizone

paulstraw

ark3typ3

Alec Gorge

paulstraw

slizone

xPaw

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