How to create custom api methods

#Creating custom API methods It is really easy to add in your API methods to JSONAPI. If you are a plugin author and want to add JSONAPI support to your plugin, scroll to the bottom of the page.

Simply create a new .json file in "plugins/JSONAPI plugin/methods/". The format for these method files looks like this:

{
	"name" : "A pretty name for the new methods",
	"namespace" : "aNamespace",
	"depends" : [
		"nameOfPluginToDependOn"
	],
	"methods" : [
		{
			"name": "nameOfTheMethod",
			"desc": "Useful description",
			"call": "Plugins.nameOfPluginToDependOn.pluginInstanceMethod(0,1,2,3)",
			"returns": ["boolean or String or int or Object or Array", "Description of what will be returned."],
			"args": [
				["argumentType", "Argument description (matches with arg 0 in the call)"],
				["argumentType", "Argument description (matches with arg 1 in the call)"],
				["argumentType", "Argument description (matches with arg 2 in the call)"],
				["argumentType", "Argument description (matches with arg 3 in the call)"]
			]
		},
		{
			"name": "nameOfTheMethod",
			"desc": "Useful description",
			"call": "Plugins.nameOfPluginToDependOn.pluginInstanceMethod(0,1,2,3)",
			"returns": ["boolean or String or int or Object or Array", "Description of what will be returned."],
			"args": [
				["argumentType", "Argument description (matches with arg 0 in the call)"],
				["argumentType", "Argument description (matches with arg 1 in the call)"],
				["argumentType", "Argument description (matches with arg 2 in the call)"],
				["argumentType", "Argument description (matches with arg 3 in the call)"]
			]
		}
	]
}

##Some notes:

• Once you define a namespace, the API method are available at namespaceName.methodName. In the example above, it would be aNamespace.nameOfTheMethod.
• Never use trailing commas in the JSON file.
• You can omit the args and returns keys and corresponding values if they are not needed for your method.

##How "call" works The call aspect of a method is what makes JSONAPI unique. It allows you call Java methods and chain the results without writing any Java.

If the text before the first period is "Server", you will now have an instance of Server and you can call all of the methods that Server has. You can even call methods on the objects returned by methods. For example, this call would cancel all methods in the scheduler:

Server.getScheduler().cancelAllTasks()

If the text before the first period is "Plugins" then the instance of plugin with the name between the first and second periods will be returned. This means you can make JSONAPi methods for plugins that don't have support built in.

##For plugin authors: how to add JSONAPI support If you want to add JSONAPI methods to your plugins, you can simply call the registerMethod or registerMethods method on the JSONAPI instance.

For example (server is an instance of Server):

server.getPluginManager().getPlugin("JSONAPI").registerMethods("{" + 
"   \"name\": \"nameOfTheMethod\"," + 
"   \"desc\": \"Useful description\"," + 
"   \"call\": \"Plugins.nameOfPluginToDependOn.pluginInstanceMethod(0,1,2,3)\"," + 
"   \"returns\": [" +
"       \"boolean or String or int or Object or Array\"," +
"       \"Description of what will be returned.\"]," + 
"   \"args\": [" + 
"       [\"argumentType\", \"Argument description (matches with arg 0 in the call)\"]," + 
"       [\"argumentType\", \"Argument description (matches with arg 1 in the call)\"]," + 
"       [\"argumentType\", \"Argument description (matches with arg 2 in the call)\"]," + 
"       [\"argumentType\", \"Argument description (matches with arg 3 in the call)\"]" + 
"   ]" + 
"}");