<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>
Bugzilla::WebService</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</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='#CALLING_METHODS'>CALLING METHODS</a>
<li class='indexItem indexItem1'><a href='#PARAMETERS'>PARAMETERS</a>
<ul class='indexList indexList2'>
<li class='indexItem indexItem2'><a href='#How_Bugzilla_WebService_Methods_Take_Parameters'>How Bugzilla WebService Methods Take Parameters</a>
</ul>
<li class='indexItem indexItem1'><a href='#LOGGING_IN'>LOGGING IN</a>
<li class='indexItem indexItem1'><a href='#STABLE%2C_EXPERIMENTAL%2C_and_UNSTABLE'>STABLE, EXPERIMENTAL, and UNSTABLE</a>
<li class='indexItem indexItem1'><a href='#ERRORS'>ERRORS</a>
<ul class='indexList indexList2'>
<li class='indexItem indexItem2'><a href='#Transient_vs._Fatal_Errors'>Transient vs. Fatal Errors</a>
<li class='indexItem indexItem2'><a href='#Unknown_Errors'>Unknown Errors</a>
</ul>
<li class='indexItem indexItem1'><a href='#COMMON_PARAMETERS'>COMMON PARAMETERS</a>
<ul class='indexList indexList2'>
<li class='indexItem indexItem2'><a href='#Limiting_What_Fields_Are_Returned'>Limiting What Fields Are Returned</a>
</ul>
<li class='indexItem indexItem1'><a href='#SEE_ALSO'>SEE ALSO</a>
<ul class='indexList indexList2'>
<li class='indexItem indexItem2'><a href='#Server_Types'>Server Types</a>
<li class='indexItem indexItem2'><a href='#WebService_Modules'>WebService Modules</a>
</ul>
</ul>
</div>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="NAME"
>NAME</a></h1>
<p>Bugzilla::WebService - The Web Service 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 is the standard API for external programs that want to interact with Bugzilla.
It provides various methods in various modules.</p>
<p>You can interact with this API via <a href="../Bugzilla/WebService/Server/XMLRPC.html" class="podlinkpod"
>XML-RPC</a> or <a href="../Bugzilla/WebService/Server/JSONRPC.html" class="podlinkpod"
>JSON-RPC</a>.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="CALLING_METHODS"
>CALLING METHODS</a></h1>
<p>Methods are grouped into "packages",
like <code class="code">Bug</code> for <a href="../Bugzilla/WebService/Bug.html" class="podlinkpod"
>Bugzilla::WebService::Bug</a>.
So,
for example,
<a href="../Bugzilla/WebService/Bug.html#get" class="podlinkpod"
>"get" in Bugzilla::WebService::Bug</a>,
is called as <code class="code">Bug.get</code>.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="PARAMETERS"
>PARAMETERS</a></h1>
<p>The Bugzilla API takes the following various types of parameters:</p>
<dl>
<dt><a name="int"
><code class="code">int</code></a></dt>
<dd>
<p>Integer.
May be null.</p>
<dt><a name="double"
><code class="code">double</code></a></dt>
<dd>
<p>A floating-point number.
May be null.</p>
<dt><a name="string"
><code class="code">string</code></a></dt>
<dd>
<p>A string.
May be null.</p>
<dt><a name="dateTime"
><code class="code">dateTime</code></a></dt>
<dd>
<p>A date/time.
Represented differently in different interfaces to this API.
May be null.</p>
<dt><a name="boolean"
><code class="code">boolean</code></a></dt>
<dd>
<p>True or false.</p>
<dt><a name="base64"
><code class="code">base64</code></a></dt>
<dd>
<p>A base64-encoded string.
This is the only way to transfer binary data via the WebService.</p>
<dt><a name="array"
><code class="code">array</code></a></dt>
<dd>
<p>An array.
There may be mixed types in an array.</p>
<p>In example code,
you will see the characters <code class="code">[</code> and <code class="code">]</code> used to represent the beginning and end of arrays.</p>
<p>In our example code in these API docs,
an array that contains the numbers 1,
2,
and 3 would look like:</p>
<pre class="code"> [1, 2, 3]</pre>
<dt><a name="struct"
><code class="code">struct</code></a></dt>
<dd>
<p>A mapping of keys to values. Called a "hash", "dict", or "map" in some other programming languages. We sometimes call this a "hash" in the API documentation.</p>
<p>The keys are strings, and the values can be any type.</p>
<p>In example code, you will see the characters <code class="code">{</code> and <code class="code">}</code> used to represent the beginning and end of structs.</p>
<p>For example, a struct with an "fruit" key whose value is "oranges", and a "vegetable" key whose value is "lettuce" would look like:</p>
<pre class="code"> { fruit => 'oranges', vegetable => 'lettuce' }</pre>
</dd>
</dl>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="How_Bugzilla_WebService_Methods_Take_Parameters"
>How Bugzilla WebService Methods Take Parameters</a></h2>
<p><b>All</b> Bugzilla WebService functions use <i>named</i> parameters. The individual <code class="code">Bugzilla::WebService::Server</code> modules explain how this is implemented for those frontends.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="LOGGING_IN"
>LOGGING IN</a></h1>
<p>There are various ways to log in:</p>
<dl>
<dt><a name="User.login"
><code class="code">User.login</code></a></dt>
<dd>
<p>You can use <a href="../Bugzilla/WebService/User.html#login" class="podlinkpod"
>"login" in Bugzilla::WebService::User</a> to log in as a Bugzilla user. This issues a token that you must then use in future calls.</p>
<dt><a name="Bugzilla_login_and_Bugzilla_password"
><code class="code">Bugzilla_login</code> and <code class="code">Bugzilla_password</code></a></dt>
<dd>
<p><b>Added in Bugzilla 3.6</b></p>
<p>You can specify <code class="code">Bugzilla_login</code> and <code class="code">Bugzilla_password</code> as arguments to any WebService method, and you will be logged in as that user if your credentials are correct. Here are the arguments you can specify to any WebService method to perform a login:</p>
<dl>
<dt><a name="Bugzilla_login_(string)_-_A_user's_login_name."
><code class="code">Bugzilla_login</code> (string) - A user's login name.</a></dt>
<dd>
<dt><a name="Bugzilla_password_(string)_-_That_user's_password."
><code class="code">Bugzilla_password</code> (string) - That user's password.</a></dt>
<dd>
<dt><a name="Bugzilla_restrictlogin_(boolean)_-_Optional._If_true,_then_your_login_will_only_be_valid_for_your_IP_address."
><code class="code">Bugzilla_restrictlogin</code> (boolean) - Optional. If true, then your login will only be valid for your IP address.</a></dt>
</dl>
<p>The <code class="code">Bugzilla_restrictlogin</code> option is only used when you have also specified <code class="code">Bugzilla_login</code> and <code class="code">Bugzilla_password</code>.</p>
<dt><a name="Bugzilla_token"
><code class="code">Bugzilla_token</code></a></dt>
<dd>
<p><b>Added in Bugzilla 5.0 and backported to 4.4.3</b></p>
<p>You can specify <code class="code">Bugzilla_token</code> as argument to any WebService method, and you will be logged in as that user if the token is correct. This is the token returned when calling <code class="code">User.login</code> mentioned above.</p>
<p>Support for using login cookies for authentication has been dropped for security reasons.</p>
</dd>
</dl>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="STABLE,_EXPERIMENTAL,_and_UNSTABLE"
>STABLE, EXPERIMENTAL, and UNSTABLE</a></h1>
<p>Methods are marked <b>STABLE</b> if you can expect their parameters and return values not to change between versions of Bugzilla. You are best off always using methods marked <b>STABLE</b>. We may add parameters and additional items to the return values, but your old code will always continue to work with any new changes we make. If we ever break a <b>STABLE</b> interface, we'll post a big notice in the Release Notes, and it will only happen during a major new release.</p>
<p>Methods (or parts of methods) are marked <b>EXPERIMENTAL</b> if we <i>believe</i> they will be stable, but there's a slight chance that small parts will change in the future.</p>
<p>Certain parts of a method's description may be marked as <b>UNSTABLE</b>, in which case those parts are not guaranteed to stay the same between Bugzilla versions.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="ERRORS"
>ERRORS</a></h1>
<p>If a particular webservice call fails, it will throw an error in the appropriate format for the frontend that you are using. For all frontends, there is at least a numeric error code and descriptive text for the error.</p>
<p>The various errors that functions can throw are specified by the documentation of those functions.</p>
<p>Each error that Bugzilla can throw has a specific numeric code that will not change between versions of Bugzilla. If your code needs to know what error Bugzilla threw, use the numeric code. Don't try to parse the description, because that may change from version to version of Bugzilla.</p>
<p>Note that if you display the error to the user in an HTML program, make sure that you properly escape the error, as it will not be HTML-escaped.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Transient_vs._Fatal_Errors"
>Transient vs. Fatal Errors</a></h2>
<p>If the error code is a number greater than 0, the error is considered "transient," which means that it was an error made by the user, not some problem with Bugzilla itself.</p>
<p>If the error code is a number less than 0, the error is "fatal," which means that it's some error in Bugzilla itself that probably requires administrative attention.</p>
<p>Negative numbers and positive numbers don't overlap. That is, if there's an error 302, there won't be an error -302.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Unknown_Errors"
>Unknown Errors</a></h2>
<p>Sometimes a function will throw an error that doesn't have a specific error code. In this case, the code will be <code class="code">-32000</code> if it's a "fatal" error, and <code class="code">32000</code> if it's a "transient" error.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="COMMON_PARAMETERS"
>COMMON PARAMETERS</a></h1>
<p>Many Webservice methods take similar arguments. Instead of re-writing the documentation for each method, we document the parameters here, once, and then refer back to this documentation from the individual methods where these parameters are used.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Limiting_What_Fields_Are_Returned"
>Limiting What Fields Are Returned</a></h2>
<p>Many WebService methods return an array of structs with various fields in the structs. (For example, <a href="../Bugzilla/WebService/Bug.html#get" class="podlinkpod"
>"get" in Bugzilla::WebService::Bug</a> returns a list of <code class="code">bugs</code> that have fields like <code class="code">id</code>, <code class="code">summary</code>, <code class="code">creation_time</code>, etc.)</p>
<p>These parameters allow you to limit what fields are present in the structs, to possibly improve performance or save some bandwidth.</p>
<dl>
<dt><a name="include_fields"
><code class="code">include_fields</code></a></dt>
<dd>
<p><code class="code">array</code> An array of strings, representing the (case-sensitive) names of fields in the return value. Only the fields specified in this hash will be returned, the rest will not be included.</p>
<p>If you specify an empty array, then this function will return empty hashes.</p>
<p>Invalid field names are ignored.</p>
<p>Example:</p>
<pre class="code"> User.get( ids => [1], include_fields => ['id', 'name'] )</pre>
<p>would return something like:</p>
<pre class="code"> { users => [{ id => 1, name => 'user@domain.com' }] }</pre>
<dt><a name="exclude_fields"
><code class="code">exclude_fields</code></a></dt>
<dd>
<p><code class="code">array</code> An array of strings, representing the (case-sensitive) names of fields in the return value. The fields specified will not be included in the returned hashes.</p>
<p>If you specify all the fields, then this function will return empty hashes.</p>
<p>Some RPC calls support specifying sub fields. If an RPC call states that it support sub field restrictions, you can restrict what information is returned within the first field. For example, if you call Product.get with an include_fields of components.name, then only the component name would be returned (and nothing else). You can include the main field, and exclude a sub field.</p>
<p>Invalid field names are ignored.</p>
<p>Specifying fields here overrides <code class="code">include_fields</code>, so if you specify a field in both, it will be excluded, not included.</p>
<p>Example:</p>
<pre class="code"> User.get( ids => [1], exclude_fields => ['name'] )</pre>
<p>would return something like:</p>
<pre class="code"> { users => [{ id => 1, real_name => 'John Smith' }] }</pre>
</dd>
</dl>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="SEE_ALSO"
>SEE ALSO</a></h1>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Server_Types"
>Server Types</a></h2>
<dl>
<dt><a name="Bugzilla::WebService::Server::XMLRPC"
><a href="../Bugzilla/WebService/Server/XMLRPC.html" class="podlinkpod"
>Bugzilla::WebService::Server::XMLRPC</a></a></dt>
<dd>
<dt><a name="Bugzilla::WebService::Server::JSONRPC"
><a href="../Bugzilla/WebService/Server/JSONRPC.html" class="podlinkpod"
>Bugzilla::WebService::Server::JSONRPC</a></a></dt>
</dl>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="WebService_Modules"
>WebService Modules</a></h2>
<dl>
<dt><a name="Bugzilla::WebService::Bug"
><a href="../Bugzilla/WebService/Bug.html" class="podlinkpod"
>Bugzilla::WebService::Bug</a></a></dt>
<dd>
<dt><a name="Bugzilla::WebService::Bugzilla"
><a href="../Bugzilla/WebService/Bugzilla.html" class="podlinkpod"
>Bugzilla::WebService::Bugzilla</a></a></dt>
<dd>
<dt><a name="Bugzilla::WebService::Classification"
><a href="../Bugzilla/WebService/Classification.html" class="podlinkpod"
>Bugzilla::WebService::Classification</a></a></dt>
<dd>
<dt><a name="Bugzilla::WebService::Group"
><a href="../Bugzilla/WebService/Group.html" class="podlinkpod"
>Bugzilla::WebService::Group</a></a></dt>
<dd>
<dt><a name="Bugzilla::WebService::Product"
><a href="../Bugzilla/WebService/Product.html" class="podlinkpod"
>Bugzilla::WebService::Product</a></a></dt>
<dd>
<dt><a name="Bugzilla::WebService::User"
><a href="../Bugzilla/WebService/User.html" class="podlinkpod"
>Bugzilla::WebService::User</a></a></dt>
</dl>
<p class="backlinkbottom"><b><a name="___bottom" href="../index.html" title="All Documents"><<</a></b></p>
<!-- end doc -->
</body></html>
distrib
>
Mageia
>
5
>
i586
>
media
>
core-updates
>
by-pkgid
>
3b735b44c1e188a44c40f81bded6b6df
>
files
>
871
