diff options
Diffstat (limited to 'Bugzilla/WebService.pm')
| -rwxr-xr-x | Bugzilla/WebService.pm | 141 |
1 files changed, 56 insertions, 85 deletions
diff --git a/Bugzilla/WebService.pm b/Bugzilla/WebService.pm index 735291fc3..ffaf7c4b7 100755 --- a/Bugzilla/WebService.pm +++ b/Bugzilla/WebService.pm @@ -22,17 +22,8 @@ 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; -} +# Used by the JSON-RPC server to convert incoming date fields apprpriately. +use constant DATE_FIELDS => {}; # For some methods, we shouldn't call Bugzilla->login before we call them use constant LOGIN_EXEMPT => { }; @@ -63,85 +54,84 @@ Bugzilla::WebService - The Web Service interface to Bugzilla 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> +You can interact with this API via +L<XML-RPC|Bugzilla::WebService::Server::XMLRPC> or +L<JSON-RPC|Bugzilla::WebService::Server::JSONRPC>. =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. +L<Bugzilla::WebService::Bug/get>, is called as C<Bug.get>. =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> >>. +The Bugzilla API takes the following various types of parameters: + +=over -=head2 Structs +=item C<int> -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. +Integer. May be null. -In example code, you will see the characters C<{> and C<}> used to represent -the beginning and end of structs. +=item C<double> -For example, here's a struct in XML-RPC: +A floating-point number. May be null. - <struct> - <member> - <name>fruit</name> - <value><string>oranges</string></value> - </member> - <member> - <name>vegetable</name> - <value><string>lettuce</string></value> - </member> - </struct> +=item C<string> -In our example code in these API docs, that would look like: +A string. May be null. - { fruit => 'oranges', vegetable => 'lettuce' } +=item C<dateTime> -=head2 Arrays +A date/time. Represented differently in different interfaces to this API. +May be null. + +=item C<boolean> + +True or false. + +=item C<array> + +An array. There may be mixed types in an array. 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: +In our example code in these API docs, an array that contains the numbers +1, 2, and 3 would look like: - <array> - <data> - <value><i4>1</i4></value> - <value><i4>2</i4></value> - <value><i4>3</i4></value> - </data> - </array> + [1, 2, 3] -In our example code in these API docs, that would look like: +=item C<struct> - [1, 2, 3] +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. + +The keys are strings, and the values can be any type. + +In example code, you will see the characters C<{> and C<}> used to represent +the beginning and end of structs. + +For example, a struct with an "fruit" key whose value is "oranges", +and a "vegetable" key whose value is "lettuce" would look like: + + { fruit => 'oranges', vegetable => 'lettuce' } + +=back =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. +B<All> Bugzilla WebService functions use I<named> parameters. +The individual C<Bugzilla::WebService::Server> modules explain +how this is implemented for those frontends. =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 +calls, so your client must be capable of receiving and transmitting cookies. =head1 STABLE, EXPERIMENTAL, and UNSTABLE @@ -164,18 +154,17 @@ 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. +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. 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. +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. 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. @@ -259,21 +248,3 @@ 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 a type called C<< <nil> >>, which is always considered -to be C<undef>, no matter what it contains. - -=begin private - -nil is implemented by XMLRPC::Lite, in XMLRPC::Deserializer::decode_value. - -=end private |