# -*- 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 # Max Kanat-Alexander # 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 The endpoint for Bugzilla WebServices is the C script in your Bugzilla installation. For example, if your Bugzilla is at C, then your XML-RPC client would access the API via: C =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 for L. So, for example, L, is called as C in XML-RPC. =head1 PARAMETERS In addition to the standard parameter types like C, C, etc., XML-RPC has two data structures, a C<< >> and an C<< >>. =head2 Structs In Perl, we call a C<< >> 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: fruit oranges vegetable lettuce 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: 1 2 3 In our example code in these API docs, that would look like: [1, 2, 3] =head2 How Bugzilla WebService Methods Take Parameters B Bugzilla WebServices functions take their parameters in a C<< >>. Another way of saying this would be: All functions take a single argument, a C<< >> that contains all parameters. The names of the parameters listed in the API docs for each function are the C element for the struct Cs. =head1 LOGGING IN You can use L 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 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. 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 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 if we I 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, 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 returns a list of C that have fields like C, C, C, 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 (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 (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, 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, C, or C fields. Bugzilla does--it treats empty values as C (called C or C in some programming languages). Bugzilla also accepts a type called C<< >>, which is always considered to be C, no matter what it contains. =begin private nil is implemented by XMLRPC::Lite, in XMLRPC::Deserializer::decode_value. =end private