<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <title> Bugzilla::WebService::Server::JSONRPC</title> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <link rel="stylesheet" title="style" type="text/css" href="../../.././../../../style.css" media="all" > </head> <body id="pod"> <p class="backlinktop"><b><a name="___top" href="../../../index.html" accesskey="1" title="All Documents"><<</a></b></p> <h1>Bugzilla::WebService::Server::JSONRPC</h1> <div class='indexgroup'> <ul class='indexList indexList1'> <li class='indexItem indexItem1'><a href='#NAME'>NAME</a> <li class='indexItem indexItem1'><a href='#DESCRIPTION'>DESCRIPTION</a> <li class='indexItem indexItem1'><a href='#JSON-RPC'>JSON-RPC</a> <li class='indexItem indexItem1'><a href='#CONNECTING'>CONNECTING</a> <li class='indexItem indexItem1'><a href='#PARAMETERS'>PARAMETERS</a> <li class='indexItem indexItem1'><a href='#ERRORS'>ERRORS</a> <li class='indexItem indexItem1'><a href='#SEE_ALSO'>SEE ALSO</a> </ul> </div> <h1><a class='u' href='#___top' title='click to go to top of document' name="NAME" >NAME</a></h1> <p>Bugzilla::WebService::Server::JSONRPC - The JSON-RPC Interface to Bugzilla</p> <h1><a class='u' href='#___top' title='click to go to top of document' name="DESCRIPTION" >DESCRIPTION</a></h1> <p>This documentation describes things about the Bugzilla WebService that are specific to JSON-RPC. For a general overview of the Bugzilla WebServices, see <a href="../../../Bugzilla/WebService.html" class="podlinkpod" >Bugzilla::WebService</a>.</p> <p>Please note that <i>everything</i> about this JSON-RPC interface is <b>EXPERIMENTAL</b>. If you want a fully stable API, please use the <code class="code">Bugzilla::WebService::Server::XMLRPC|XML-RPC</code> interface.</p> <h1><a class='u' href='#___top' title='click to go to top of document' name="JSON-RPC" >JSON-RPC</a></h1> <p>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.</p> <p>At some point in the future, Bugzilla may also support JSON-RPC 2.0.</p> <p>The JSON-RPC standards are described at <a href="http://json-rpc.org/" class="podlinkurl" >http://json-rpc.org/</a>.</p> <h1><a class='u' href='#___top' title='click to go to top of document' name="CONNECTING" >CONNECTING</a></h1> <p>The endpoint for the JSON-RPC interface is the <code class="code">jsonrpc.cgi</code> script in your Bugzilla installation. For example, if your Bugzilla is at <code class="code">bugzilla.yourdomain.com</code>, then your JSON-RPC client would access the API via: <code class="code">http://bugzilla.yourdomain.com/jsonrpc.cgi</code></p> <p>Bugzilla only allows JSON-RPC requests over <code class="code">POST</code>. <code class="code">GET</code> requests (or any other type of request, such as <code class="code">HEAD</code>) will be denied.</p> <h1><a class='u' href='#___top' title='click to go to top of document' name="PARAMETERS" >PARAMETERS</a></h1> <p>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 <code class="code">foo</code> and the other called <code class="code">bar</code>, the <code class="code">params</code> element of your JSON-RPC call would look like:</p> <pre class="code"> "params": [{ "foo": 1, "bar": "something" }]</pre> <p>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.</p> <p><code class="code">dateTime</code> fields are strings in the standard ISO-8601 format: <code class="code">YYYY-MM-DDTHH:MM:SSZ</code>, where <code class="code">T</code> and <code class="code">Z</code> 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.)</p> <p>All other types are standard JSON types.</p> <h1><a class='u' href='#___top' title='click to go to top of document' name="ERRORS" >ERRORS</a></h1> <p>JSON-RPC 1.0 and JSON-RPC 1.1 both return an <code class="code">error</code> element when they throw an error. In Bugzilla, the error contents look like:</p> <pre class="code"> { message: 'Some message here', code: 123 }</pre> <p>So, for example, in JSON-RPC 1.0, an error response would look like:</p> <pre class="code"> { result: null, error: { message: 'Some message here', code: 123 }, id: 1 }</pre> <p>Every error has a "code", as described in <a href="../../../Bugzilla/WebService.html#ERRORS" class="podlinkpod" >"ERRORS" in Bugzilla::WebService</a>. Errors with a numeric <code class="code">code</code> higher than 100000 are errors thrown by the JSON-RPC library that Bugzilla uses, not by Bugzilla.</p> <h1><a class='u' href='#___top' title='click to go to top of document' name="SEE_ALSO" >SEE ALSO</a></h1> <p><a href="../../../Bugzilla/WebService.html" class="podlinkpod" >Bugzilla::WebService</a></p> <p class="backlinkbottom"><b><a name="___bottom" href="../../../index.html" title="All Documents"><<</a></b></p> <!-- end doc --> </body></html>