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
Bugzilla only allows JSON-RPC requests over POST.
GET requests (or any other type of request,
such as HEAD) will be denied.
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.)
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.