<!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>
<ul class='indexList indexList2'>
<li class='indexItem indexItem2'><a href='#Connecting_via_GET'>Connecting via GET</a>
<li class='indexItem indexItem2'><a href='#JSONP'>JSONP</a>
</ul>
<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>
<li class='indexItem indexItem1'><a href='#Methods_in_need_of_POD'>Methods in need of POD</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>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Connecting_via_GET"
>Connecting via GET</a></h2>
<p>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.</p>
<p>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 <code class="code">Bugzilla_login</code> and <code class="code">Bugzilla_password</code> method described at <a href="../../../Bugzilla/WebService.html#LOGGING_IN" class="podlinkpod"
>"LOGGING IN" in Bugzilla::WebService</a>.</p>
<p>To connect over GET,
simply send the values that you'd normally send for each JSON-RPC argument as URL parameters,
with the <code class="code">params</code> item being a JSON string.</p>
<p>The simplest example is a call to <code class="code">Bugzilla.time</code>:</p>
<pre class="code"> jsonrpc.cgi?method=Bugzilla.time</pre>
<p>Here's a call to <code class="code">User.get</code>, with several parameters:</p>
<pre class="code"> jsonrpc.cgi?method=User.get&params=[ { "ids": [1,2], "names": ["user@domain.com"] } ]</pre>
<p>Although in reality you would url-encode the <code class="code">params</code> argument, so it would look more like this:</p>
<pre class="code"> jsonrpc.cgi?method=User.get&params=%5B+%7B+%22ids%22%3A+%5B1%2C2%5D%2C+%22names%22%3A+%5B%22user%40domain.com%22%5D+%7D+%5D</pre>
<p>You can also specify <code class="code">version</code> as a URL parameter, if you want to specify what version of the JSON-RPC protocol you're using, and <code class="code">id</code> as a URL parameter if you want there to be a specific <code class="code">id</code> value in the returned JSON-RPC response.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="JSONP"
>JSONP</a></h2>
<p>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 <a href="http://bob.pythonmac.org/archives/2005/12/05/remote-json-jsonp/" class="podlinkurl"
>http://bob.pythonmac.org/archives/2005/12/05/remote-json-jsonp/</a>.</p>
<p>To use JSONP with Bugzilla's JSON-RPC WebService, simply specify a <code class="code">callback</code> 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 <code class="code">Bugzilla.time</code> on a remote website, using JSONP:</p>
<pre class="code"> <script type="text/javascript"
src="http://bugzilla.example.com/jsonrpc.cgi?method=Bugzilla.time&amp;callback=foo"></pre>
<p>That would call the <code class="code">Bugzilla.time</code> method and pass its value to a function called <code class="code">foo</code> as the only argument. All the other URL parameters (such as <code class="code">params</code>, for passing in arguments to methods) that can be passed to <code class="code">jsonrpc.cgi</code> during GET requests are also available, of course. The above is just the simplest possible example.</p>
<p>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.</p>
<p>The <code class="code">callback</code> URL parameter may only contain letters, numbers, periods, and the underscore (<code class="code">_</code>) character. Including any other characters will cause Bugzilla to throw an error. (This error will be a normal JSON-RPC response, not JSONP.)</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><code class="code">base64</code> 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.</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>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="Methods_in_need_of_POD"
><b>Methods in need of POD</b></a></h1>
<dl>
<dt><a name="response"
>response</a></dt>
<dd>
<dt><a name="response_header"
>response_header</a></dt>
<dd>
<dt><a name="cgi"
>cgi</a></dt>
<dd>
<dt><a name="retrieve_json_from_get"
>retrieve_json_from_get</a></dt>
<dd>
<dt><a name="create_json_coder"
>create_json_coder</a></dt>
<dd>
<dt><a name="type"
>type</a></dt>
<dd>
<dt><a name="handle_login"
>handle_login</a></dt>
<dd>
<dt><a name="datetime_format_outbound"
>datetime_format_outbound</a></dt>
</dl>
<p class="backlinkbottom"><b><a name="___bottom" href="../../../index.html" title="All Documents"><<</a></b></p>
<!-- end doc -->
</body></html>
