5.7.95. Bugzilla::WebService::Server::JSONRPC¶
5.7.95.1. NAME¶
Bugzilla::WebService::Server::JSONRPC - The JSON-RPC Interface to Bugzilla
5.7.95.2. DESCRIPTION¶
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.
5.7.95.3. JSON-RPC¶
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/.
5.7.95.4. CONNECTING¶
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
Connecting via GET¶
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
Bugzilla::WebService/LOGGING IN.
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.
JSONP¶
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.)
5.7.95.5. PARAMETERS¶
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.
5.7.95.6. ERRORS¶
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 Bugzilla::WebService/ERRORS.
Errors with a numeric code
higher than 100000 are errors thrown by
the JSON-RPC library that Bugzilla uses, not by Bugzilla.