<<

# Bugzilla::WebService::Server::JSONRPC

- NAME
- DESCRIPTION
- JSON-RPC
- CONNECTING
- PARAMETERS
- ERRORS
- SEE ALSO

# NAME

Bugzilla::WebService::Server::JSONRPC - The JSON-RPC Interface to Bugzilla

# 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.

# 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/.

# 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`

Bugzilla only allows JSON-RPC requests over `POST`. `GET` requests (or any other type of request, such as `HEAD`) will be denied.

# 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.)

All other types are standard JSON types.

# 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 "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.

# SEE ALSO

Bugzilla::WebService

<<