294 lines
9.6 KiB
Perl
294 lines
9.6 KiB
Perl
# -*- Mode: perl; indent-tabs-mode: nil -*-
|
|
#
|
|
# The contents of this file are subject to the Mozilla Public
|
|
# License Version 1.1 (the "License"); you may not use this file
|
|
# except in compliance with the License. You may obtain a copy of
|
|
# the License at http://www.mozilla.org/MPL/
|
|
#
|
|
# Software distributed under the License is distributed on an "AS
|
|
# IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
|
|
# implied. See the License for the specific language governing
|
|
# rights and limitations under the License.
|
|
#
|
|
# The Original Code is the Bugzilla Bug Tracking System.
|
|
#
|
|
# Contributor(s): Marc Schumann <wurblzap@gmail.com>
|
|
# Max Kanat-Alexander <mkanat@bugzilla.org>
|
|
# Rosie Clarkson <rosie.clarkson@planningportal.gov.uk>
|
|
#
|
|
# Portions © Crown copyright 2009 - Rosie Clarkson (development@planningportal.gov.uk) for the Planning Portal
|
|
|
|
# This is the base class for $self in WebService method calls. For the
|
|
# actual RPC server, see Bugzilla::WebService::Server and its subclasses.
|
|
package Bugzilla::WebService;
|
|
use strict;
|
|
use Date::Parse;
|
|
use XMLRPC::Lite;
|
|
|
|
sub datetime_format {
|
|
my ($self, $date_string) = @_;
|
|
|
|
my $time = str2time($date_string);
|
|
my ($sec, $min, $hour, $mday, $mon, $year) = localtime $time;
|
|
# This format string was stolen from SOAP::Utils->format_datetime,
|
|
# which doesn't work but which has almost the right format string.
|
|
my $iso_datetime = sprintf('%d%02d%02dT%02d:%02d:%02d',
|
|
$year + 1900, $mon + 1, $mday, $hour, $min, $sec);
|
|
return $iso_datetime;
|
|
}
|
|
|
|
# For some methods, we shouldn't call Bugzilla->login before we call them
|
|
use constant LOGIN_EXEMPT => { };
|
|
|
|
sub login_exempt {
|
|
my ($class, $method) = @_;
|
|
|
|
return $class->LOGIN_EXEMPT->{$method};
|
|
}
|
|
|
|
sub type {
|
|
my ($self, $type, $value) = @_;
|
|
if ($type eq 'dateTime') {
|
|
$value = $self->datetime_format($value);
|
|
}
|
|
return XMLRPC::Data->type($type)->value($value);
|
|
}
|
|
|
|
1;
|
|
|
|
__END__
|
|
|
|
=head1 NAME
|
|
|
|
Bugzilla::WebService - The Web Service interface to Bugzilla
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
This is the standard API for external programs that want to interact
|
|
with Bugzilla. It provides various methods in various modules.
|
|
|
|
Currently the only method of accessing the API is via XML-RPC. The XML-RPC
|
|
standard is described here: L<http://www.xmlrpc.com/spec>
|
|
|
|
The endpoint for Bugzilla WebServices is the C<xmlrpc.cgi> script in
|
|
your Bugzilla installation. For example, if your Bugzilla is at
|
|
C<bugzilla.yourdomain.com>, then your XML-RPC client would access the
|
|
API via: C<http://bugzilla.yourdomain.com/xmlrpc.cgi>
|
|
|
|
=head1 CALLING METHODS
|
|
|
|
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.
|
|
|
|
Methods are grouped into "packages", like C<Bug> for
|
|
L<Bugzilla::WebService::Bug>. So, for example,
|
|
L<Bugzilla::WebService::Bug/get>, is called as C<Bug.get> in XML-RPC.
|
|
|
|
=head1 PARAMETERS
|
|
|
|
In addition to the standard parameter types like C<int>, C<string>, etc.,
|
|
XML-RPC has two data structures, a C<< <struct> >> and an C<< <array> >>.
|
|
|
|
=head2 Structs
|
|
|
|
In Perl, we call a C<< <struct> >> a "hash" or a "hashref". You may see
|
|
us refer to it that way in the API documentation.
|
|
|
|
In example code, you will see the characters C<{> and C<}> used to represent
|
|
the beginning and end of structs.
|
|
|
|
For example, here's a struct in XML-RPC:
|
|
|
|
<struct>
|
|
<member>
|
|
<name>fruit</name>
|
|
<value><string>oranges</string></value>
|
|
</member>
|
|
<member>
|
|
<name>vegetable</name>
|
|
<value><string>lettuce</string></value>
|
|
</member>
|
|
</struct>
|
|
|
|
In our example code in these API docs, that would look like:
|
|
|
|
{ fruit => 'oranges', vegetable => 'lettuce' }
|
|
|
|
=head2 Arrays
|
|
|
|
In example code, you will see the characters C<[> and C<]> used to
|
|
represent the beginning and end of arrays.
|
|
|
|
For example, here's an array in XML-RPC:
|
|
|
|
<array>
|
|
<data>
|
|
<value><i4>1</i4></value>
|
|
<value><i4>2</i4></value>
|
|
<value><i4>3</i4></value>
|
|
</data>
|
|
</array>
|
|
|
|
In our example code in these API docs, that would look like:
|
|
|
|
[1, 2, 3]
|
|
|
|
=head2 How Bugzilla WebService Methods Take Parameters
|
|
|
|
B<All> Bugzilla WebServices functions take their parameters in
|
|
a C<< <struct> >>. Another way of saying this would be: All functions
|
|
take a single argument, a C<< <struct> >> that contains all parameters.
|
|
The names of the parameters listed in the API docs for each function are
|
|
the C<name> element for the struct C<member>s.
|
|
|
|
=head1 LOGGING IN
|
|
|
|
You can use L<Bugzilla::WebService::User/login> 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.
|
|
|
|
=head1 STABLE, EXPERIMENTAL, and UNSTABLE
|
|
|
|
Methods are marked B<STABLE> 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>. 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> interface, we'll post a big notice in the Release Notes,
|
|
and it will only happen during a major new release.
|
|
|
|
Methods (or parts of methods) are marked B<EXPERIMENTAL> if
|
|
we I<believe> they will be stable, but there's a slight chance that
|
|
small parts will change in the future.
|
|
|
|
Certain parts of a method's description may be marked as B<UNSTABLE>,
|
|
in which case those parts are not guaranteed to stay the same between
|
|
Bugzilla versions.
|
|
|
|
=head1 ERRORS
|
|
|
|
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.
|
|
|
|
The various errors that functions can throw are specified by the
|
|
documentation of those functions.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
=head2 Transient vs. Fatal Errors
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
Negative numbers and positive numbers don't overlap. That is, if there's
|
|
an error 302, there won't be an error -302.
|
|
|
|
=head2 Unknown Errors
|
|
|
|
Sometimes a function will throw an error that doesn't have a specific
|
|
error code. In this case, the code will be C<-32000> if it's a "fatal"
|
|
error, and C<32000> if it's a "transient" error.
|
|
|
|
=head1 COMMON PARAMETERS
|
|
|
|
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.
|
|
|
|
=head2 Limiting What Fields Are Returned
|
|
|
|
Many WebService methods return an array of structs with various
|
|
fields in the structs. (For example, L<Bugzilla::WebService::Bug/get>
|
|
returns a list of C<bugs> that have fields like C<id>, C<summary>,
|
|
C<creation_time>, etc.)
|
|
|
|
These parameters allow you to limit what fields are present in
|
|
the structs, to possibly improve performance or save some bandwidth.
|
|
|
|
=over
|
|
|
|
=item C<include_fields> (array)
|
|
|
|
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.
|
|
|
|
If you specify an empty array, then this function will return empty
|
|
hashes.
|
|
|
|
Invalid field names are ignored.
|
|
|
|
Example:
|
|
|
|
User.get( ids => [1], include_fields => ['id', 'name'] )
|
|
|
|
would return something like:
|
|
|
|
{ users => [{ id => 1, name => 'user@domain.com' }] }
|
|
|
|
=item C<exclude_fields> (array)
|
|
|
|
An array of strings, representing the (case-sensitive) names of fields.
|
|
The fields specified will not be included in the returned hashes.
|
|
|
|
If you specify all the fields, then this function will return empty
|
|
hashes.
|
|
|
|
Invalid field names are ignored.
|
|
|
|
Specifying fields here overrides C<include_fields>, so if you specify a
|
|
field in both, it will be excluded, not included.
|
|
|
|
Example:
|
|
|
|
User.get( ids => [1], exclude_fields => ['name'] )
|
|
|
|
would return something like:
|
|
|
|
{ users => [{ id => 1, real_name => 'John Smith' }] }
|
|
|
|
=back
|
|
|
|
|
|
=head1 EXTENSIONS TO THE XML-RPC STANDARD
|
|
|
|
=head2 Undefined Values
|
|
|
|
Normally, XML-RPC does not allow empty values for C<int>, C<double>, or
|
|
C<dateTime.iso8601> fields. Bugzilla does--it treats empty values as
|
|
C<undef> (called C<NULL> or C<None> in some programming languages).
|
|
|
|
Bugzilla also accepts an element called C<< <nil> >>, as specified by
|
|
the XML-RPC extension here: L<http://ontosys.com/xml-rpc/extensions.php>,
|
|
which is always considered to be C<undef>, no matter what it contains.
|
|
|
|
Bugzilla does not use C<< <nil> >> values in returned data, because currently
|
|
most clients do not support C<< <nil> >>. Instead, any fields with C<undef>
|
|
values will be stripped from the response completely. Therefore
|
|
B<the client must handle the fact that some expected fields may not be
|
|
returned>.
|
|
|
|
=begin private
|
|
|
|
nil is implemented by XMLRPC::Lite, in XMLRPC::Deserializer::decode_value
|
|
in the CPAN SVN since 14th Dec 2008
|
|
L<http://rt.cpan.org/Public/Bug/Display.html?id=20569> and in Fedora's
|
|
perl-SOAP-Lite package in versions 0.68-1 and above.
|
|
|
|
=end private
|