Bugzilla::WebService::Server::JSONRPC - The JSON-RPC Interface to Bugzilla
This documentation describes things about the Bugzilla WebService that are specific to JSON-RPC. For a general overview of the Bugzilla WebServices, see Bugzilla::WebService.
Please note that everything about this JSON-RPC interface is EXPERIMENTAL.
If you want a fully stable API,
please use the Bugzilla::WebService::Server::XMLRPC|XML-RPC interface.
Bugzilla supports both JSON-RPC 1.0 and 1.1. We recommend that you use JSON-RPC 1.0 instead of 1.1, though, because 1.1 is deprecated.
At some point in the future, Bugzilla may also support JSON-RPC 2.0.
The JSON-RPC standards are described at http://json-rpc.org/.
The endpoint for the JSON-RPC interface is the jsonrpc.cgi script in your Bugzilla installation.
For example,
if your Bugzilla is at bugzilla.yourdomain.com,
then your JSON-RPC client would access the API via: http://bugzilla.yourdomain.com/jsonrpc.cgi
The most powerful way to access the JSON-RPC interface is by HTTP POST. However, for convenience, you can also access certain methods by using GET (a normal webpage load). Methods that modify the database or cause some action to happen in Bugzilla cannot be called over GET. Only methods that simply return data can be used over GET.
For security reasons,
when you connect over GET,
cookie authentication is not accepted.
If you want to authenticate using GET,
you have to use the Bugzilla_login and Bugzilla_password method described at "LOGGING IN" in Bugzilla::WebService.
To connect over GET,
simply send the values that you'd normally send for each JSON-RPC argument as URL parameters,
with the params item being a JSON string.
The simplest example is a call to Bugzilla.time:
jsonrpc.cgi?method=Bugzilla.time
Here's a call to User.get, with several parameters:
jsonrpc.cgi?method=User.get¶ms=[ { "ids": [1,2], "names": ["user@domain.com"] } ]
Although in reality you would url-encode the params argument, so it would look more like this:
jsonrpc.cgi?method=User.get¶ms=%5B+%7B+%22ids%22%3A+%5B1%2C2%5D%2C+%22names%22%3A+%5B%22user%40domain.com%22%5D+%7D+%5D
You can also specify version as a URL parameter, if you want to specify what version of the JSON-RPC protocol you're using, and id as a URL parameter if you want there to be a specific id value in the returned JSON-RPC response.
When calling the JSON-RPC WebService over GET, you can use the "JSONP" method of doing cross-domain requests, if you want to access the WebService directly on a web page from another site. JSONP is described at http://bob.pythonmac.org/archives/2005/12/05/remote-json-jsonp/.
To use JSONP with Bugzilla's JSON-RPC WebService, simply specify a callback parameter to jsonrpc.cgi when using it via GET as described above. For example, here's some HTML you could use to get the data from Bugzilla.time on a remote website, using JSONP:
<script type="text/javascript"
src="http://bugzilla.example.com/jsonrpc.cgi?method=Bugzilla.time&callback=foo">
That would call the Bugzilla.time method and pass its value to a function called foo as the only argument. All the other URL parameters (such as params, for passing in arguments to methods) that can be passed to jsonrpc.cgi during GET requests are also available, of course. The above is just the simplest possible example.
The values returned when using JSONP are identical to the values returned when not using JSONP, so you will also get error messages if there is an error.
The callback URL parameter may only contain letters, numbers, periods, and the underscore (_) character. Including any other characters will cause Bugzilla to throw an error. (This error will be a normal JSON-RPC response, not JSONP.)
For JSON-RPC 1.0, the very first parameter should be an object containing the named parameters. For example, if you were passing two named parameters, one called foo and the other called bar, the params element of your JSON-RPC call would look like:
"params": [{ "foo": 1, "bar": "something" }]
For JSON-RPC 1.1, you can pass parameters either in the above fashion or using the standard named-parameters mechanism of JSON-RPC 1.1.
dateTime fields are strings in the standard ISO-8601 format: YYYY-MM-DDTHH:MM:SSZ, where T and Z are a literal T and Z, respectively. The "Z" means that all times are in UTC timezone--times are always returned in UTC, and should be passed in as UTC. (Note: The JSON-RPC interface currently also accepts non-UTC times for any values passed in, if they include a time-zone specifier that follows the ISO-8601 standard, instead of "Z" at the end. This behavior is expected to continue into the future, but to be fully safe for forward-compatibility with all future versions of Bugzilla, it is safest to pass in all times as UTC with the "Z" timezone specifier.)
base64 fields are strings that have been base64 encoded. Note that although normal base64 encoding includes newlines to break up the data, newlines within a string are not valid JSON, so you should not insert newlines into your base64-encoded string.
All other types are standard JSON types.
JSON-RPC 1.0 and JSON-RPC 1.1 both return an error element when they throw an error. In Bugzilla, the error contents look like:
{ message: 'Some message here', code: 123 }
So, for example, in JSON-RPC 1.0, an error response would look like:
{
result: null,
error: { message: 'Some message here', code: 123 },
id: 1
}
Every error has a "code", as described in "ERRORS" in Bugzilla::WebService. Errors with a numeric code higher than 100000 are errors thrown by the JSON-RPC library that Bugzilla uses, not by Bugzilla.