<!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='#Structs'>Structs</a>
<li class='indexItem indexItem2'><a href='#Arrays'>Arrays</a>
<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='#EXTENSIONS_TO_THE_XML-RPC_STANDARD'>EXTENSIONS TO THE XML-RPC STANDARD</a>
<ul class='indexList indexList2'>
<li class='indexItem indexItem2'><a href='#Undefined_Values'>Undefined Values</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>Currently the only method of accessing the API is via XML-RPC.
The XML-RPC standard is described here: <a href="http://www.xmlrpc.com/spec" class="podlinkurl"
>http://www.xmlrpc.com/spec</a></p>
<p>The endpoint for Bugzilla WebServices is the <code class="code">xmlrpc.cgi</code> script in your Bugzilla installation.
For example,
if your Bugzilla is at <code class="code">bugzilla.yourdomain.com</code>,
then your XML-RPC client would access the API via: <code class="code">http://bugzilla.yourdomain.com/xmlrpc.cgi</code></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 called in the normal XML-RPC fashion.
Bugzilla does not currently implement any extensions to the standard method of XML-RPC method calling.</p>
<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> in XML-RPC.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="PARAMETERS"
>PARAMETERS</a></h1>
<p>In addition to the standard parameter types like <code class="code">int</code>,
<code class="code">string</code>,
etc.,
XML-RPC has two data structures,
a <code class="code"><struct></code> and an <code class="code"><array></code>.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Structs"
>Structs</a></h2>
<p>In Perl,
we call a <code class="code"><struct></code> a "hash" or a "hashref".
You may see us refer to it that way in the API documentation.</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,
here's a struct in XML-RPC:</p>
<pre class="code"> <struct>
<member>
<name>fruit</name>
<value><string>oranges</string></value>
</member>
<member>
<name>vegetable</name>
<value><string>lettuce</string></value>
</member>
</struct></pre>
<p>In our example code in these API docs, that would look like:</p>
<pre class="code"> { fruit => 'oranges', vegetable => 'lettuce' }</pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Arrays"
>Arrays</a></h2>
<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>For example, here's an array in XML-RPC:</p>
<pre class="code"> <array>
<data>
<value><i4>1</i4></value>
<value><i4>2</i4></value>
<value><i4>3</i4></value>
</data>
</array></pre>
<p>In our example code in these API docs, that would look like:</p>
<pre class="code"> [1, 2, 3]</pre>
<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 WebServices functions take their parameters in a <code class="code"><struct></code>. Another way of saying this would be: All functions take a single argument, a <code class="code"><struct></code> that contains all parameters. The names of the parameters listed in the API docs for each function are the <code class="code">name</code> element for the struct <code class="code">member</code>s.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="LOGGING_IN"
>LOGGING IN</a></h1>
<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 standard HTTP cookies that you must then use in future calls, so your XML-RPC client must be capable of receiving and transmitting cookies.</p>
<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 a standard XML-RPC error. There will be a numeric error code, and then the description field will contain descriptive text of the error. Each error that Bugzilla can throw has a specific code that will not change between versions of Bugzilla.</p>
<p>The various errors that functions can throw are specified by the documentation of those functions.</p>
<p>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_(array)"
><code class="code">include_fields</code> (array)</a></dt>
<dd>
<p>An array of strings, representing the (case-sensitive) names of fields. 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_(array)"
><code class="code">exclude_fields</code> (array)</a></dt>
<dd>
<p>An array of strings, representing the (case-sensitive) names of fields. 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>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="EXTENSIONS_TO_THE_XML-RPC_STANDARD"
>EXTENSIONS TO THE XML-RPC STANDARD</a></h1>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Undefined_Values"
>Undefined Values</a></h2>
<p>Normally, XML-RPC does not allow empty values for <code class="code">int</code>, <code class="code">double</code>, or <code class="code">dateTime.iso8601</code> fields. Bugzilla does--it treats empty values as <code class="code">undef</code> (called <code class="code">NULL</code> or <code class="code">None</code> in some programming languages).</p>
<p>Bugzilla also accepts an element called <code class="code"><nil></code>, as specified by the XML-RPC extension here: <a href="http://ontosys.com/xml-rpc/extensions.php" class="podlinkurl"
>http://ontosys.com/xml-rpc/extensions.php</a>, which is always considered to be <code class="code">undef</code>, no matter what it contains.</p>
<p>Bugzilla does not use <code class="code"><nil></code> values in returned data, because currently most clients do not support <code class="code"><nil></code>. Instead, any fields with <code class="code">undef</code> values will be stripped from the response completely. Therefore <b>the client must handle the fact that some expected fields may not be returned</b>.</p>
<p class="backlinkbottom"><b><a name="___bottom" href="../index.html" title="All Documents"><<</a></b></p>
<!-- end doc -->
</body></html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
eede4b249967833a1b10737cc411ef80
>
files
>
656
