[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 4, 2011

From my phone I don't see anything wrong. However pho is not a good language for testing streams. I'll check it when home.

Alec Gorge · May 4, 2011

@Tajin You had an error in your code. You need to have a newline at the end of every request:

PHP:

echo fwrite($tcp, "/api/subscribe?source=console&key=".$key."\n");

Also I would use stream_get_line instead of fgets for retrieving data. That way you know you have valid JSON that you can parse.

The Javascript one will never work because the callback is only ever executed when the whole http document loads, which it never will because of the nature of JSONAPI's streams. There is currently no way to have streams work via Javascript. Also the callback would fail because the document does not contain valid JSON. Each line is valid JSON, but as a whole, it is invalid.

Phinary · May 5, 2011

Hmm this still seems to confuse me. Can you show me how to use the console command function. Here is the example of what i wanna do

mysql_query("UPDATE logins SET mccoin=mccoin-20 WHERE username='$username'")
then do console command = /manselect world
then do console command = /manuadd $username Donator

can you show me how I would do this please

Alec Gorge · May 5, 2011

This should work:

PHP:

$api = new JSONAPI("host", port, "username", "pass", "salt"); $api->callMultiple(array( "runConsoleCommand" "runConsoleCommand" ), array( "manselect world", "manuadd $username Donator" ));

Keep in mind that this makes a request to your server to it could take a while to execute.

Tajin · May 5, 2011

Ok cool, that did the trick, seems pretty slow though.

Hmm, not sure if you want to add it and/or if it would be better off in a seperate plugin...
How about allowing users to define urls for each source where the data should be sent to via a simple http request.

Something like this in the properties:

consoleLogToURL = http://myurl.com/stuff/console.php
chatLogToURL = http://myurl.com/stuff/chatbot.php

So whenever there's a new line, it's encoded and sent directly to the coresponding url.

Maybe I'm mistaken but I think atleast for php this would be more useful and much easier to handle.

ps.: making progress on the inventory-editor

Alec Gorge · May 5, 2011

It isn't slow. PHP is slow. You do not want to use streams from within PHP. I do like your idea about the URLs where you can have the latest 50 items sent. I would probably would just expose it as another standard method. having JSONAPI post so frequently to all those URLs is just suicide for performance.

I can add a Socket.IO server in and then you can access the streams from the client. That makes more sense to me.

skimberk1 · May 5, 2011

Tajin said: ↑

Ok cool, that did the trick, seems pretty slow though.

Hmm, not sure if you want to add it and/or if it would be better off in a seperate plugin...
How about allowing users to define urls for each source where the data should be sent to via a simple http request.

Something like this in the properties:

So whenever there's a new line, it's encoded and sent directly to the coresponding url.

Maybe I'm mistaken but I think atleast for php this would be more useful and much easier to handle.

ps.: making progress on the inventory-editor

Looks really nice, any chance you get send me the item images? I've been wanting to make something like that, but couldn't find item pictures...

Tajin · May 5, 2011

I'm using the ones from minecraft-wiki, basically those are just the items.png and terrain.png from minecraft. You can either cut those into seperate files or use css-styles to crop them (better).

Here's an array matching item-ids to those images (first part: Blocks, second part: Icons, 53 and 67 are cobble/wooden stairs)

PHP:

<?php $icons = Array( "2", "1", "3", "0", "5", "43", "0", "45", "46", "0", "0", "30", "38", "37", "0", "6", "4", "7", "12", "13", "17", "0", "42", "41", "57", "0", "0", "54", "40", "39", "0", "0", "14", "15", "16", "47", "48", "49", "0", "0", "0", "0", "0", "0", "61", "0", "23", "0", "19", "20", "56", "73", "0", "18", "0", "0", "0", "0", "0", "0", "58", "62", "0","6.1", "35", "52", "80", "79", "0", "0", "81", "0", "82", "83", "25", "84", "0", "0", "0","6.2", "50", "0", "0", "65", "0", "0", "0", "60", "0", "0", "0", "0", "0", "0", "0", "59", "0", "0", "0", "76", "0", "0", "0", "87", "88", "89", "0", "0", "0", "0", "0", "0", "0","35.15","35.7", "75","17.1","17.2","0", "86", "91", "92", "0", "0", "0", "0", "0", "0", "66","35.14","35.6", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "22","35.13","35.5", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "21","35.12","35.4", "27", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0","35.11","35.3", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "24","35.10","35.2", "28", "0", "0", "0", "0", "0", "0","44.1","44.3","0", "0", "0", "0", "0","35.9 ","35.1", "0", "0", "0", "0", "0", "0", "0","44.2","44", "0", "90", "85", "0", "0","35.8 ", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "77", "0", "0", "-2", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "51", "-1", "10", "8", "298","302","306","310","314","259","318","263","287","295","260","322","344","353","332","-10", "299","303","307","311","315","261","336","265","288","296","321","338","352","354","341","-11", "300","304","308","312","316","262", "0","266","289","297","323","324","330","355", "0","-12", "301","305","309","313","317","280","345","264","331","337","339","340", "0", "0", "0","-13", "268","272","267","276","283","346","347","281","282","348","325","326","327","335", "351", "351.8", "269","273","256","277","284", "0","356","319","320","349","350", "0","357", "0", "351.1", "351.9", "270","274","257","278","285", "0", "0","334","329", "0", "0", "0", "0", "0", "351.2", "351.10", "271","275","258","279","286", "0", "0", "0", "0", "0", "0", "0", "0", "0", "351.3", "351.11", "290","291","292","293","294", "0", "0","328","333", "0", "0", "0", "0", "0", "351.4", "351.12", "0", "0", "0", "0", "0", "0", "0","342", "0", "0", "0", "0", "0", "0", "351.5", "351.13", "0", "0", "0", "0", "0", "0", "0","343", "0", "0", "0", "0", "0", "0", "351.6", "351.14", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "351.7", "351.15", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "2256","2257","0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "53","67"); ?>

Phinary · May 5, 2011

I get this whenever I try to do a command

2011-05-05 09:11:24 [INFO] [JSONAPI] [API Call] 50.72.112.144: method=runConsoleCommand?args=["manselect world"]
2011-05-05 09:11:24 [INFO] [JSONAPI] [Java Wrapper] §cYou are not allowed to use that command.
2011-05-05 09:11:24 [INFO] [JSONAPI] [Java Wrapper] /manselect <world>

Alec Gorge · May 6, 2011

Version 1.4 released:

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

@Tajin I have added in the 3 new methods that should help you with your PHP. Also, I forgot to mention that the inventory editor looks fantastic. I look forward to seeing it released.

@Shaun Bennett Sorry about that. JSONAPI was running commands as a low-level user, it wasn't actually sending them to the console. Download 1.4 to fix this problem.

xPaw · May 6, 2011

Oh that is nice update you've got there! Good job

Alec Gorge · May 6, 2011

@xPaw Thanks!

Alec Gorge · May 7, 2011

Version 1.4.1 released

update the WebSocket server support the new HyBi-07 spec

xPaw · May 7, 2011

system.getCpuUsage just returns 1 all the time.. tested on windows and linux servers

Alec Gorge · May 7, 2011

Yeah, I have noticed that too. I cannot find a Java solution that accurately measures CPU usage though. I may just have to remove that.

xPaw · May 7, 2011

Damnit

- Can you add optional parameter to methods you've added in 1.4, so you can pass unixtime in it, and it will return logs starting from that time. I wanted to make ajax-refreshing console, so it loads fresh logs each time, and not just latest 50

EDIT: Why there is 'itemInHand' and 'inventory'->'hand' saying the same info?
I think you should get rid off one of those. (talking about getPlayer)

Alec Gorge · May 7, 2011

I can add that. I will add that later today.

For convenience. I am wary to remove anything for BC reasons at this point.

NotoriousPyro · May 8, 2011

@Alec Gorge Any idea where I'm going wrong with phpMCWeb?

PHP:

<?php define("___ACCESS", TRUE); require("../includes.php"); require("../inc/jsonapi.php"); $api = new JSONAPI($jsonapi_ip, $jsonapi_port, $jsonapi_username, $jsonapi_password, $jsonapi_salt); $cpu = $api->call("system.getCpuUsage"); var_dump($cpu); ?>

Seems to always return:
HTML:
array(3) {
	["result"]=> string(7) "success"
	["source"]=> string(18) "system.getCpuUsage"
	["success"]=> float(1)
}
A float of 1 all the time?

Edit: I see the above posts that it is a recognised fault. Have you taken a look at this: http://stackoverflow.com/questions/...e-computers-cpu-memory-and-disk-usage-in-java

Apologies if you have.

xPaw · May 8, 2011

@NotoriousPyro look couple of posts above

NotoriousPyro · May 8, 2011

@xPaw read my edit

Alec Gorge · May 8, 2011

@NotoriousPyro I cannot use SIGAR due to its size (4mb+). I will look into OperatingSystemMXBean again. I did before and support seemed kind of sketchy among non-Oracle/Sun JVMs.

NotoriousPyro · May 8, 2011

@Alec Gorge Screw the non-Oracle systems, it's up to them to improve support for it.

Alec Gorge · May 10, 2011

Okay, I tried using the OperatingSystemMXBean method to no avail (it always returns 0 for the CPU usage).

I am thinking I may just drop CPU usage (because it doesn't work) and system memory (it introduces a 100kb overhead and I can't imagine how it is all that useful).

Memory usage/free for Minecraft specifically would stay, and so would disk susage.

What do you guys think?

NotoriousPyro · May 11, 2011

Agreed, but it would've been nice to have CPU usage .

Are you going to add more built-in APIs? I've also been working on converting phpMCWeb to this and it's working well, http://craigcrawford.dyndns.org/phpmcweb/

A sample of the code for the chat page:

PHP:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <style type="text/css"> body,td,th { font-family: "Lucida Console", Monaco, monospace; font-size: 11px; color: #FFF; } </style> </head> <body> <?php define("___ACCESS", TRUE); require("../../includes.php"); require("../../inc/jsonapi.php"); $api = new JSONAPI($jsonapi_ip, $jsonapi_port, $jsonapi_username, $jsonapi_password, $jsonapi_salt); $data = $api->call("getLatestChats"); $data = array_reverse($data["success"]); foreach ($data as $message => $value) { $left = $left.date("H:i", $data[$message]["time"])." ".$data[$message]["player"].": \n"; $right = $right.$data[$message]["message"]."\n"; if (strlen($data[$message]["message"]) > 75) { $left = $left."\n"; } } echo "<div style=\"width: 25%; float: left;\">".nl2br($left)."</div> <div style=\"width: 75%; float: left;\">".nl2br($right)."</div>"; ?> </body> </html>

Thanks for your hard work Alec.

Alec Gorge · May 11, 2011

@NotoriousPyro Yeah, I know .

I can add in as many APIs as you request. I have really just done the ones that I could think of, I am sure there is many more that I have not thought of.

Nice job so far!

No problem. But yeah, I have put in upwards of 30 hours on JSONAPI so far (probably 15 or so before it was even released to the public).

NotoriousPyro · May 11, 2011

@Alec Gorge, is there any possibility of you implementing a way to chat with users as if you were ingame via the API?

I.e. Via a specified username, and message which also is displayed via getLatestChats and server log, etc?

Edit: Also, it would be nice if we could specify how much data we want returned? For example, only 10 last chats, etc?

Alec Gorge · May 11, 2011

@NotoriousPyro I am not sure if I follow. You can just use the broadcast method.

Yes I can do that second thing. It will be in v1.5.

NotoriousPyro · May 11, 2011

@Alec Gorge, it doesn't matter about the first point - I will just prefix the message with a specified username

NynjaWitay · May 12, 2011

I'm really enjoying this plugin.

I installed 1.1 and got it all working, and I setup a simple display on my page that shows all of the plugins I am running and what versions they all have. Well, I just updated to 1.4.1 and it still says that I am running 1.1. The new system commands work, but the version displayed with "method=getServerVersion?args=[]" is wrong; It still says 1.1. Did you forget to update the version string?

Alec Gorge · May 12, 2011

@NotoriousPyro Sounds good.

@NynjaWitay True. I have forgotten to update the version string. I don't like how Bukkit makes me place it in the yml file. That is fixed for 1.5!

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

Alec Gorge

Phinary

Alec Gorge

Tajin

Alec Gorge

skimberk1

Tajin

Phinary

Alec Gorge

xPaw

Alec Gorge

Alec Gorge

xPaw

Alec Gorge

xPaw

Alec Gorge

NotoriousPyro

xPaw

NotoriousPyro

Alec Gorge

NotoriousPyro

Alec Gorge

NotoriousPyro

Alec Gorge

NotoriousPyro

Alec Gorge

NotoriousPyro

NynjaWitay

Alec Gorge

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