<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>6.1.1. General — Bugzilla 5.0.4 documentation</title>
<link rel="stylesheet" href="../../../_static/bugzilla.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../../',
VERSION: '5.0.4',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="../../../_static/jquery.js"></script>
<script type="text/javascript" src="../../../_static/underscore.js"></script>
<script type="text/javascript" src="../../../_static/doctools.js"></script>
<link rel="shortcut icon" href="../../../_static/favicon.ico"/>
<link rel="search" title="Search" href="../../../search.html" />
<link rel="next" title="6.1.2. Attachments" href="attachment.html" />
<link rel="prev" title="6.1. Core API v1" href="index.html" />
</head>
<body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="attachment.html" title="6.1.2. Attachments"
accesskey="N">next</a></li>
<li class="right" >
<a href="index.html" title="6.1. Core API v1"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../../../index.html">Bugzilla 5.0.4 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="../../index.html" >6. WebService API Reference</a> »</li>
<li class="nav-item nav-item-2"><a href="index.html" accesskey="U">6.1. Core API v1</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="general">
<h1>6.1.1. General<a class="headerlink" href="#general" title="Permalink to this headline">¶</a></h1>
<p>This is the standard REST API for external programs that want to interact
with Bugzilla. It provides a REST interface to various Bugzilla functions.</p>
<div class="section" id="basic-information">
<h2>6.1.1.1. Basic Information<a class="headerlink" href="#basic-information" title="Permalink to this headline">¶</a></h2>
<p><strong>Browsing</strong></p>
<p>If the <code class="docutils literal"><span class="pre">Accept</span></code> header of a request is set to <code class="docutils literal"><span class="pre">text/html</span></code> (as it is by an
ordinary web browser) then the API will return the JSON data as a HTML
page which the browser can display. In other words, you can play with the
API using just your browser to see results in a human-readable form.
This is a good way to try out the various GET calls, even if you can't use
it for POST or PUT.</p>
<p><strong>Data Format</strong></p>
<p>The REST API only supports JSON input, and either JSON or JSONP output.
So objects sent and received must be in JSON format.</p>
<p>On every request, you must set both the <code class="docutils literal"><span class="pre">Accept</span></code> and <code class="docutils literal"><span class="pre">Content-Type</span></code> HTTP
headers to the MIME type of the data format you are using to communicate with
the API. <code class="docutils literal"><span class="pre">Content-Type</span></code> tells the API how to interpret your request, and
<code class="docutils literal"><span class="pre">Accept</span></code> tells it how you want your data back. <code class="docutils literal"><span class="pre">Content-Type</span></code> must be
<code class="docutils literal"><span class="pre">application/json</span></code>. <code class="docutils literal"><span class="pre">Accept</span></code> can be either that, or
<code class="docutils literal"><span class="pre">application/javascript</span></code> for JSONP. In the latter`case, add a <code class="docutils literal"><span class="pre">callback</span></code>
parameter to name your callback.</p>
<p>Parameters may also be passed in as part of the query string for non-GET
requests and will override any matching parameters in the request body.</p>
<p>Example request which returns the current version of Bugzilla:</p>
<div class="highlight-http"><div class="highlight"><pre><span></span><span class="nf">GET</span> <span class="nn">/rest/version</span> <span class="kr">HTTP</span><span class="o">/</span><span class="m">1.1</span>
<span class="na">Host</span><span class="o">:</span> <span class="l">bugzilla.example.com</span>
<span class="na">Accept</span><span class="o">:</span> <span class="l">application/json</span>
</pre></div>
</div>
<p>Example response:</p>
<div class="highlight-http"><div class="highlight"><pre><span></span><span class="kr">HTTP</span><span class="o">/</span><span class="m">1.1</span> <span class="m">200</span> <span class="ne">OK</span>
<span class="na">Vary</span><span class="o">:</span> <span class="l">Accept</span>
<span class="na">Content-Type</span><span class="o">:</span> <span class="l">application/json</span>
<span class="p">{</span>
<span class="nt">"version"</span> <span class="p">:</span> <span class="s2">"4.2.9+"</span>
<span class="p">}</span>
</pre></div>
</div>
<p><strong>Errors</strong></p>
<p>When an error occurs over REST, an object is returned with the key <code class="docutils literal"><span class="pre">error</span></code>
set to <code class="docutils literal"><span class="pre">true</span></code>.</p>
<p>The error contents look similar to:</p>
<div class="highlight-js"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="s2">"error"</span><span class="o">:</span> <span class="kc">true</span><span class="p">,</span>
<span class="s2">"message"</span><span class="o">:</span> <span class="s2">"Some message here"</span><span class="p">,</span>
<span class="s2">"code"</span><span class="o">:</span> <span class="mi">123</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="common-data-types">
<h2>6.1.1.2. Common Data Types<a class="headerlink" href="#common-data-types" title="Permalink to this headline">¶</a></h2>
<p>The Bugzilla API uses the following various types of parameters:</p>
<table border="1" class="docutils">
<colgroup>
<col width="10%" />
<col width="90%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">type</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>int</td>
<td>Integer.</td>
</tr>
<tr class="row-odd"><td>double</td>
<td>A floating-point number.</td>
</tr>
<tr class="row-even"><td>string</td>
<td>A string.</td>
</tr>
<tr class="row-odd"><td>email</td>
<td>A string representing an email address. This value, when returned,
may be filtered based on if the user is logged in or not.</td>
</tr>
<tr class="row-even"><td>date</td>
<td>A specific date. Example format: <code class="docutils literal"><span class="pre">YYYY-MM-DD</span></code>.</td>
</tr>
<tr class="row-odd"><td>datetime</td>
<td>A date/time. Timezone should be in UTC unless otherwise noted.
Example format: <code class="docutils literal"><span class="pre">YYYY-MM-DDTHH24:MI:SSZ</span></code>.</td>
</tr>
<tr class="row-even"><td>boolean</td>
<td><code class="docutils literal"><span class="pre">true</span></code> or <code class="docutils literal"><span class="pre">false</span></code>.</td>
</tr>
<tr class="row-odd"><td>base64</td>
<td>A base64-encoded string. This is the only way to transfer
binary data via the API.</td>
</tr>
<tr class="row-even"><td>array</td>
<td>An array. There may be mixed types in an array. <code class="docutils literal"><span class="pre">[</span></code> and <code class="docutils literal"><span class="pre">]</span></code> are
used to represent the beginning and end of arrays.</td>
</tr>
<tr class="row-odd"><td>object</td>
<td>A mapping of keys to values. Called a "hash", "dict", or "map" in
some other programming languages. The keys are strings, and the
values can be any type. <code class="docutils literal"><span class="pre">{</span></code> and <code class="docutils literal"><span class="pre">}</span></code> are used to represent the
beginning and end of objects.</td>
</tr>
</tbody>
</table>
<p>Parameters that are required will be displayed in <strong>bold</strong> in the parameters
table for each API method.</p>
</div>
<div class="section" id="authentication">
<h2>6.1.1.3. Authentication<a class="headerlink" href="#authentication" title="Permalink to this headline">¶</a></h2>
<p>Some methods do not require you to log in. An example of this is
<a class="reference internal" href="bug.html#rest-single-bug"><span class="std std-ref">Get Bug</span></a>. However, authenticating yourself allows you to see
non-public information, for example, a bug that is not publicly visible.</p>
<p>There are two ways to authenticate yourself:</p>
<p><strong>API Keys</strong></p>
<p>You can specify <code class="docutils literal"><span class="pre">Bugzilla_api_key</span></code> or simply <code class="docutils literal"><span class="pre">api_key</span></code> as an argument to
any call, and you will be logged in as that user if the key is correct and has
not been revoked. You can set up an API key by using the 'API Key' tab in the
Preferences pages.</p>
<p><strong>Login and Password</strong></p>
<p>You can specify <code class="docutils literal"><span class="pre">Bugzilla_login</span></code> and <code class="docutils literal"><span class="pre">Bugzilla_password</span></code> or simply
<code class="docutils literal"><span class="pre">login</span></code> and <code class="docutils literal"><span class="pre">password</span></code> respectively, as arguments to any call, and you will
be logged in as that user if your credentials are correct.</p>
<table border="1" class="docutils">
<colgroup>
<col width="29%" />
<col width="9%" />
<col width="61%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">name</th>
<th class="head">type</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>Bugzilla_login</strong></td>
<td>string</td>
<td>A user's login name.</td>
</tr>
<tr class="row-odd"><td><strong>Bugzilla_password</strong></td>
<td>string</td>
<td>That user's password.</td>
</tr>
<tr class="row-even"><td>Bugzilla_restrictlogin</td>
<td>boolean</td>
<td>If true, then your login will only be
valid for your IP address.</td>
</tr>
</tbody>
</table>
<p>The <code class="docutils literal"><span class="pre">Bugzilla_restrictlogin</span></code> option is only used when you have also
specified <code class="docutils literal"><span class="pre">Bugzilla_login</span></code> and <code class="docutils literal"><span class="pre">Bugzilla_password</span></code>.</p>
<p>There is also a deprecated method of authentication described below that will be
removed in the version after Bugzilla 5.0.</p>
<p><strong>Bugzilla Tokens</strong></p>
<p>You can use <a class="reference internal" href="user.html#rest-user-login"><span class="std std-ref">Login</span></a> to log in as a Bugzilla user. This issues a
token that you must then use in future calls. Just use the value for <code class="docutils literal"><span class="pre">token</span></code>
and pass as either <code class="docutils literal"><span class="pre">Bugzilla_token</span></code> or simply <code class="docutils literal"><span class="pre">token</span></code> as arguments to an
API call.</p>
<table border="1" class="docutils">
<colgroup>
<col width="24%" />
<col width="8%" />
<col width="68%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">name</th>
<th class="head">type</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>Bugzilla_token</strong></td>
<td>string</td>
<td>You can specify this as argument to any call,
and you will be logged in as that user if the
token is correct. This is the token returned
when calling <a class="reference internal" href="user.html#rest-user-login"><span class="std std-ref">Login</span></a> mentioned
above.</td>
</tr>
</tbody>
</table>
<p>An error is thrown if you pass an invalid token; you will need to log in again
to get a new token.</p>
<p>Also starting with Bugzilla 5.0, login cookies are no longer returned by
<a class="reference internal" href="user.html#rest-user-login"><span class="std std-ref">Login</span></a> due to security concerns.</p>
</div>
<div class="section" id="useful-parameters">
<h2>6.1.1.4. Useful Parameters<a class="headerlink" href="#useful-parameters" title="Permalink to this headline">¶</a></h2>
<p>Many calls take common arguments. These are documented below and linked from
the individual calls where these parameters are used.</p>
<p><strong>Including Fields</strong></p>
<p>Many calls return an array of objects with various fields in the objects. (For
example, <a class="reference internal" href="bug.html#rest-single-bug"><span class="std std-ref">Get Bug</span></a> returns a list of <code class="docutils literal"><span class="pre">bugs</span></code> that have fields like
<code class="docutils literal"><span class="pre">id</span></code>, <code class="docutils literal"><span class="pre">summary</span></code>, <code class="docutils literal"><span class="pre">creation_time</span></code>, etc.)</p>
<p>These parameters allow you to limit what fields are present in the objects, to
improve performance or save some bandwidth.</p>
<p><code class="docutils literal"><span class="pre">include_fields</span></code>: The (case-sensitive) names of fields in the response data.
Only the fields specified in the object will be returned, the rest will not be
included. Fields should be comma delimited.</p>
<p>Invalid field names are ignored.</p>
<p>Example request to <a class="reference internal" href="user.html#rest-user-get"><span class="std std-ref">Get User</span></a>:</p>
<div class="highlight-text"><div class="highlight"><pre><span></span>GET /rest/user/1?include_fields=id,name
</pre></div>
</div>
<p>would return something like:</p>
<div class="highlight-js"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="s2">"users"</span> <span class="o">:</span> <span class="p">[</span>
<span class="p">{</span>
<span class="s2">"id"</span> <span class="o">:</span> <span class="mi">1</span><span class="p">,</span>
<span class="s2">"name"</span> <span class="o">:</span> <span class="s2">"user@domain.com"</span>
<span class="p">}</span>
<span class="p">]</span>
<span class="p">}</span>
</pre></div>
</div>
<p><strong>Excluding Fields</strong></p>
<p><code class="docutils literal"><span class="pre">exclude_fields</span></code>: The (case-sensitive) names of fields in the return value. Thefields specified will not be included in the returned hashes. Fields should
be comma delimited.</p>
<p>Invalid field names are ignored.</p>
<p>Specifying fields here overrides <code class="docutils literal"><span class="pre">include_fields</span></code>, so if you specify a
field in both, it will be excluded, not included.</p>
<p>Example request to <a class="reference internal" href="user.html#rest-user-get"><span class="std std-ref">Get User</span></a>:</p>
<div class="highlight-js"><div class="highlight"><pre><span></span><span class="nx">GET</span> <span class="o">/</span><span class="nx">rest</span><span class="o">/</span><span class="nx">user</span><span class="o">/</span><span class="mi">1</span><span class="o">?</span><span class="nx">exclude_fields</span><span class="o">=</span><span class="nx">name</span>
</pre></div>
</div>
<p>would return something like:</p>
<div class="highlight-js"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="s2">"users"</span> <span class="o">:</span> <span class="p">[</span>
<span class="p">{</span>
<span class="s2">"id"</span> <span class="o">:</span> <span class="mi">1</span><span class="p">,</span>
<span class="s2">"real_name"</span> <span class="o">:</span> <span class="s2">"John Smith"</span>
<span class="p">}</span>
<span class="p">]</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Some calls support specifying "subfields". If a call states that it supports
"subfield" restrictions, you can restrict what information is returned within
the first field. For example, if you call <a class="reference internal" href="product.html#rest-product-get"><span class="std std-ref">Get Product</span></a> with an
<code class="docutils literal"><span class="pre">include_fields</span></code> of <code class="docutils literal"><span class="pre">components.name</span></code>, then only the component name would be
returned (and nothing else). You can include the main field, and exclude a
subfield.</p>
<p>There are several shortcut identifiers to ask for only certain groups of
fields to be returned or excluded:</p>
<table border="1" class="docutils">
<colgroup>
<col width="12%" />
<col width="88%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">value</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>_all</td>
<td>All possible fields are returned if this is specified in
<code class="docutils literal"><span class="pre">include_fields</span></code>.</td>
</tr>
<tr class="row-odd"><td>_default</td>
<td>Default fields are returned if <code class="docutils literal"><span class="pre">include_fields</span></code> is empty or
this is specified. This is useful if you want the default
fields in addition to a field that is not normally returned.</td>
</tr>
<tr class="row-even"><td>_extra</td>
<td>Extra fields are not returned by default and need to be manually
specified in <code class="docutils literal"><span class="pre">include_fields</span></code> either by exact field name, or adding
<code class="docutils literal"><span class="pre">_extra</span></code>.</td>
</tr>
<tr class="row-odd"><td>_custom</td>
<td>Custom fields are normally returned by default unless this is added
to <code class="docutils literal"><span class="pre">exclude_fields</span></code>. Also you can use it in <code class="docutils literal"><span class="pre">include_fields</span></code> if
for example you want specific field names plus all custom fields.
Custom fields are normally only relevant to bug objects.</td>
</tr>
</tbody>
</table>
<hr class="docutils" />
<p>This documentation undoubtedly has bugs; if you find some, please file
them <a class="reference external" href="https://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&component=Documentation">here</a>.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../../../index.html">
<img class="logo" src="../../../_static/bugzilla.png" alt="Logo"/>
</a></p>
<h3><a href="../../../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">6.1.1. General</a><ul>
<li><a class="reference internal" href="#basic-information">6.1.1.1. Basic Information</a></li>
<li><a class="reference internal" href="#common-data-types">6.1.1.2. Common Data Types</a></li>
<li><a class="reference internal" href="#authentication">6.1.1.3. Authentication</a></li>
<li><a class="reference internal" href="#useful-parameters">6.1.1.4. Useful Parameters</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="index.html"
title="previous chapter">6.1. Core API v1</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="attachment.html"
title="next chapter">6.1.2. Attachments</a></p>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="../../../search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="attachment.html" title="6.1.2. Attachments"
>next</a></li>
<li class="right" >
<a href="index.html" title="6.1. Core API v1"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../../../index.html">Bugzilla 5.0.4 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="../../index.html" >6. WebService API Reference</a> »</li>
<li class="nav-item nav-item-2"><a href="index.html" >6.1. Core API v1</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.6.6.
</div>
</body>
</html>
