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

I think something was being cached somewhere.

Alec Gorge · May 2, 2011

@NynjaWitay Try this jar, and tell me if it fixes that problem: https://github.com/alecgorge/jsonap...b04db6af5e0/test/plugins/JSONAPI.jar?raw=true

wallnuss · May 2, 2011

NotoriuosPyro mentoined that to me and I think I will drop PyBukkitWeb and instead release a Python/Djanog lib for it. Nicely done it looks simply and beautiful. (And I don't need to use XmlRpc anymore).

/edit

And as soon as I get to it teclp will be using this.

Misa · May 2, 2011

will you keep it updated for the next CB releases ? it's the best api for minecraft servers.

Alec Gorge · May 2, 2011

@wallnuss thanks! I look forward to seeing your pull request. XMLRPC does suck doesn't it?

@Misa I will always keep it updated. My design allows for very rapid updates too because the API methods are separated from the actual Java code. I also use this with my own server and community so it will remain updated.

Of course, donating promotes speed and keeps me interested and happy.

wallnuss · May 2, 2011

Alec Gorge said: ↑

@wallnuss thanks! I look forward to seeing your pull request. XMLRPC does suck doesn't it? [...]

Yeah XMLRPC sucks as does everything that uses xml ...

one question for a Javascript app I just could use jquery to pull the Informations. The problem altough is I don't want to save my key e.g. password and username in a javascript file. Could you add a option for public requests ?

In PyBukkitWeb I added Servlet through wich you could published any Information as json.

Alec Gorge · May 2, 2011

For client side apps I find it is best to simply precalculate the hash. This keeps people from just randomly spammin a server.

All the same, how do you think this should be implemented? Should there just be a whitelist file?

xPaw · May 2, 2011

Could you add 2 methods for getting CPU and RAM usage?

Alec Gorge · May 2, 2011

@xPaw I will add that.

@wallnuss I'll just go ahead and add a whitelist.

Phinary · May 3, 2011

Is there a way to change a users group with this and groupmanager without them being logged in? Im setting up auto donation things and I want to be able to change the users group. I know you can if they are logged in using a console command but when they arent logged in the console command doesnt work,

Alec Gorge · May 3, 2011

@Shaun Bennett Probably. Can you give me a link to the group manager that you are talking about?

Phinary · May 3, 2011

I use essential group manager since the group manager by anjocaido is dead.

Link here - http://ess.earth2me.com/index.php/Group_Manager/Commands

I tried to use the command manuadd but my issue is that that command doesnt work if the player isnt logged in.

Phinary · May 3, 2011

Alec Gorge said: ↑

@Shaun Bennett Probably. Can you give me a link to the group manager that you are talking about?

Also, I know php but i have no idea what JSON is really. Think you can add a simple script on using this to output players online.

skimberk1 · May 3, 2011

Hmm, would it be possible to have a very simple example of the streaming? Just needa know how to access the actual stream...
But yeah, awesome plugin! Gonna make a full fledged inventory editor with lots of prettiness just for the heck of it lol.

NynjaWitay · May 3, 2011

Code:

23:05:41 [INFO] [JSONAPI] Waiting 20 seconds to load methods so that all the other plugins load...
23:05:41 [INFO] Nether v1.1 enabled
23:05:41 [INFO] Loading map 'org.dynmap.flat.FlatMap'...
23:05:41 [INFO] Loading map 'org.dynmap.kzedmap.KzedMap'...
23:05:41 [INFO] Loading renderer 'org.dynmap.kzedmap.DefaultTileRenderer'...
23:05:41 [INFO] Loading renderer 'org.dynmap.kzedmap.CaveTileRenderer'...
23:05:41 [INFO] Activated world 'world' in Dynmap.
23:05:41 [INFO] Loading map 'org.dynmap.kzedmap.KzedMap'...
23:05:41 [INFO] Loading renderer 'org.dynmap.kzedmap.DefaultTileRenderer'...
...
23:05:41 [INFO] Done (0.169s)! For help, type "help" or "?"
...
23:06:02 [INFO] [JSONAPI] 41 methods loaded in 2 namespaces.
23:06:02 [INFO] [JSONAPI] JSON Server listening on 20059
23:06:02 [INFO] [JSONAPI] JSON Stream Server listening on 20060
23:06:02 [INFO] [JSONAPI] Active and listening for requests.
23:06:19 [INFO] [JSONAPI] [API Call] 0:0:0:0:0:0:0:1: method=getServerVersion?args=[]
23:06:19 [INFO] [JSONAPI] [API Call] 0:0:0:0:0:0:0:1: method=getPlugins?args=[]
23:06:39 [INFO] [JSONAPI] [API Call] 0:0:0:0:0:0:0:1: method=dynmap.getPort?args=[]

EDIT: had a typo and was calling "GetPort and not getPort"

Your fix worked. Loading it 20 seconds later might be a bit excessive since it loads in 0.169s. Maybe there is a hook for post loading or when that done message is displayed?

Tajin · May 3, 2011

Shaun Bennett said: ↑

I know you can if they are logged in using a console command but when they arent logged in the console command doesnt work,

When a player is not logged in you can simply change his settings by editing the files on your server. So just open (for example) the "..GroupManager/worlds/worldX/users.yml" file via php and make ur changes there. Same thing also works when editing the inventory of a player that is offline. (except you have to work with a .dat file there)

Oh and about that example, here.... as simple as it gets:

PHP:

<?php require('JSONAPI.php'); $json = new JSONAPI('localhost', '20059', 'username', 'password', 'salt'); print_r($json->call('getPlayerCount',Array())); ?>

xPaw · May 3, 2011

am i missing something, or there is no method to get server port? If there isn't, please add getServerPort

Alec Gorge · May 3, 2011

@xPaw I just updated the PHP SDK to expose the 4 fields: host, port, username, password and salt. You can now access the port (if you download the new SDK) by doing $api->port.

@Shaun Bennett You can read more about JSON at http://www.json.org/. Also Tajin had a good idea.

@skimberk1 Oh, yeah, I'll throw up a quick example this afternoon.

@NynjaWitay Good. Okay, I'll reduce the time to 5 seconds or so.

You can view other examples on the wiki https://github.com/alecgorge/jsonapi/wiki

Also this afternoon JSONAPI v1.3 will be out with a plethora of new features, bug fixes and developer tools. I wanted to get it out last night, but didn't quite finish.

xPaw · May 3, 2011

Alec Gorge said: ↑

@xPaw I just updated the PHP SDK to expose the 4 fields: host, port, username, password and salt. You can now access the port (if you download the new SDK) by doing $api->port..

But this gets the port you access API on. I want to get the server port it self

Tajin · May 3, 2011

I forgot to mention it in my last postm theres a pretty good PHPclass for reading/writing NBT files available:
http://www.minecraftforum.net/viewtopic.php?f=1022&t=130643

So in combination with this API here we can edit inventories of both online and offline players without much hassle.

Oh, one more thing: Could you add the armor-slots to "setPlayerInventorySlot" and "SetPlayerInventorySlotWithDamage"?

Also this afternoon JSONAPI v1.3 will be out with a plethora of new features, bug fixes and developer tools.

After that I suggest you sit back and enjoy a nice cup of tea/coffee while we do our stuff. My head is ringing with all the possibilities this API already offers. ^^

Phinary · May 3, 2011

My PHP script is on a different server then my Dedicated server. So I don't believe that's possible

xPaw · May 3, 2011

I have another request. Could you add property to disable stream listening?
I mean this:
Code:
[JSONAPI] JSON Stream Server listening on 20060
I dont need it, and i want to disable it

KokaKiwi · May 3, 2011

Woh!!! It's more advanced than my plugin, ApiCraft x)
Good work!
I think I'll use it for my own server haha xD

Alec Gorge · May 4, 2011

1.3 is released. See original post for changelog.

Also check this out: http://alecgorge.github.com/jsonapi/

@KokaKiwi Thanks! Haha, good luck and tell me how it goes.

@Shaun Bennett You can edit offline players as long as you turn online validation off using /mantogglevalidate. I am not sure if this is persistent (stays the same when you turn off the server and turn it back on):
Code:
  mantogglevalidate:
    description: Toggle on/off the validating if player is online.
    usage: /<command>
    permission: groupmanager.mantogglevalidate
This should give you a good start though.

@xPaw I added getServerPort and getServerIp. However, I will not add an option to disable the streaming api. It will only cause headaches in the future. If you don't want it used, don't open the port.

@Tajin I have added support for armor using the slots specified in this handy-dandy picture:

Alec Gorge · May 4, 2011

@skimberk1 Here is the stream documentation: https://github.com/alecgorge/jsonapi/wiki/How-to-use-the-stream-api-over-a-socket-connection and https://github.com/alecgorge/jsonapi/wiki/Stream-sources

edit: also, I released JSONAPI 1.3.1. It fixes a few bugs with streams.

Phinary · May 4, 2011

Alec Gorge said: ↑
1.3 is released. See original post for changelog.

Also check this out: http://alecgorge.github.com/jsonapi/

@KokaKiwi Thanks! Haha, good luck and tell me how it goes.

@Shaun Bennett You can edit offline players as long as you turn online validation off using /mantogglevalidate. I am not sure if this is persistent (stays the same when you turn off the server and turn it back on):
Code:
  mantogglevalidate:
    description: Toggle on/off the validating if player is online.
    usage: /<command>
    permission: groupmanager.mantogglevalidate
This should give you a good start though.

@xPaw I added getServerPort and getServerIp. However, I will not add an option to disable the streaming api. It will only cause headaches in the future. If you don't want it used, don't open the port.

@Tajin I have added support for armor using the slots specified in this handy-dandy picture:
Thanks so much! This helped a ton!

Alec Gorge · May 4, 2011

@Shaun Bennett Tell me if you get everything working! Your problem is pretty common!

skimberk1 · May 4, 2011

Would it be possible to add a method kinda like getPlayer but that would work when player is offline? So that I can check players' inventory and the like when they're offline. Thanks.

xPaw · May 4, 2011

system.getCpuUsage returns always 1 for me (i was testing on Windows, havent on Linux yet)

Tajin · May 4, 2011

I cant seem to get any response via stream.

Anything wrong with this one?:

PHP:

<?php require('JSONAPI.php'); $json = new JSONAPI('localhost', '20060', 'user', 'pw', 'salt'); $key = $json->createKey("console"); $tcp = fsockopen('localhost',20060); stream_set_blocking ($tcp,1); if (!$tcp) { echo "$errstr ($errno)<br />\n"; } else { echo fwrite($tcp, "/api/subscribe?source=console&key=".$key); while (!feof($tcp)) { echo fgets($tcp, 128); } fclose($tcp); } ?>

Same thing with JS:
Code:
api = new JSONAPI({
                    host: "xxx",
                    port: 20059,
                    username: "yyy",
                    password: "zzz",
                    salt: 'salt'
                });
                key = api.createKey('chat');
                jQuery.getJSON("http://url.com:20059/api/subscribe?source=chat&key="+key+"&callback=?", function (data) {
                    alert(data);
                });
... no response

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

wallnuss

Misa

Alec Gorge

wallnuss

Alec Gorge

xPaw

Alec Gorge

Phinary

Alec Gorge

Phinary

Phinary

skimberk1

NynjaWitay

Tajin

xPaw

Alec Gorge

xPaw

Tajin

Phinary

xPaw

KokaKiwi

Alec Gorge

Alec Gorge

Phinary

Alec Gorge

skimberk1

xPaw

Tajin

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