diff options
| -rwxr-xr-x | Bugzilla/WebService.pm | 81 | ||||
| -rwxr-xr-x | Bugzilla/WebService/Bug.pm | 48 | ||||
| -rwxr-xr-x | Bugzilla/WebService/Bugzilla.pm | 26 | ||||
| -rwxr-xr-x | Bugzilla/WebService/Product.pm | 20 | ||||
| -rwxr-xr-x | Bugzilla/WebService/User.pm | 39 | ||||
| -rw-r--r-- | Bugzilla/WebService/Util.pm | 11 |
6 files changed, 192 insertions, 33 deletions
diff --git a/Bugzilla/WebService.pm b/Bugzilla/WebService.pm index d1502468d..438a66710 100755 --- a/Bugzilla/WebService.pm +++ b/Bugzilla/WebService.pm @@ -159,6 +159,87 @@ 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> + +=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 diff --git a/Bugzilla/WebService/Bug.pm b/Bugzilla/WebService/Bug.pm index d60f5015b..aaaf753a3 100755 --- a/Bugzilla/WebService/Bug.pm +++ b/Bugzilla/WebService/Bug.pm @@ -268,14 +268,16 @@ or get information about bugs that have already been filed. =head1 METHODS -See L<Bugzilla::WebService> for a description of B<STABLE>, B<UNSTABLE>, -and B<EXPERIMENTAL>. +See L<Bugzilla::WebService> for a description of how parameters are passed, +and what B<STABLE>, B<UNSTABLE>, and B<EXPERIMENTAL> mean. =head2 Utility Functions =over -=item C<legal_values> B<EXPERIMENTAL> +=item C<legal_values> + +B<EXPERIMENTAL> =over @@ -320,11 +322,13 @@ You specified a field that doesn't exist or isn't a drop-down field. =back -=head2 Bug Creation and Modification +=head2 Bug Information =over -=item C<get> B<EXPERIMENTAL> +=item C<get> + +B<EXPERIMENTAL> =over @@ -410,7 +414,9 @@ You do not have access to the bug_id you specified. =back -=item C<get_history> B<UNSTABLE> +=item C<get_history> + +B<UNSTABLE> =over @@ -497,9 +503,25 @@ present in this hash. The same as L</get>. +=item B<History> + +=over + +=item Added in Bugzilla B<3.4>. + +=back + +=back + =back -=item C<create> B<EXPERIMENTAL> +=head2 Bug Creation and Modification + +=over + +=item C<create> + +B<EXPERIMENTAL> =over @@ -640,7 +662,9 @@ B<Required>, due to a bug in Bugzilla. =back -=item C<add_comment> B<EXPERIMENTAL> +=item C<add_comment> + +B<EXPERIMENTAL> =over @@ -688,6 +712,14 @@ You did not have the necessary rights to edit the bug. =back +=item B<History> + +=over + +=item Added in Bugzilla B<3.2>. + +=back + =back diff --git a/Bugzilla/WebService/Bugzilla.pm b/Bugzilla/WebService/Bugzilla.pm index 5196834df..2f35bbe59 100755 --- a/Bugzilla/WebService/Bugzilla.pm +++ b/Bugzilla/WebService/Bugzilla.pm @@ -71,12 +71,14 @@ This provides functions that tell you about Bugzilla in general. =head1 METHODS -See L<Bugzilla::WebService> for a description of what B<STABLE>, B<UNSTABLE>, -and B<EXPERIMENTAL> mean. +See L<Bugzilla::WebService> for a description of how parameters are passed, +and what B<STABLE>, B<UNSTABLE>, and B<EXPERIMENTAL> mean. =over -=item C<version> B<EXPERIMENTAL> +=item C<version> + +B<STABLE> =over @@ -95,7 +97,9 @@ string. =back -=item C<extensions> B<EXPERIMENTAL> +=item C<extensions> + +B<EXPERIMENTAL> =over @@ -113,9 +117,19 @@ contains the names of extensions as keys, and information about the extension as values. One of the values that must be returned is the 'version' of the extension +=item B<History> + +=over + +=item Added in Bugzilla B<3.2>. + +=back + =back -=item C<timezone> B<EXPERIMENTAL> +=item C<timezone> + +B<STABLE> =over @@ -129,7 +143,7 @@ returns will be in this timezone. =item B<Returns> -A hash with a single item, C<timezone>, that is the timezone as a +A hash with a single item, C<timezone>, that is the timezone offset as a string in (+/-)XXXX (RFC 2822) format. =back diff --git a/Bugzilla/WebService/Product.pm b/Bugzilla/WebService/Product.pm index 0f15a7e30..4dd894453 100755 --- a/Bugzilla/WebService/Product.pm +++ b/Bugzilla/WebService/Product.pm @@ -86,14 +86,16 @@ get information about them. =head1 METHODS -See L<Bugzilla::WebService> for a description of what B<STABLE>, B<UNSTABLE>, -and B<EXPERIMENTAL> mean, and for more information about error codes. +See L<Bugzilla::WebService> for a description of how parameters are passed, +and what B<STABLE>, B<UNSTABLE>, and B<EXPERIMENTAL> mean. =head2 List Products =over -=item C<get_selectable_products> B<UNSTABLE> +=item C<get_selectable_products> + +B<EXPERIMENTAL> =over @@ -112,7 +114,9 @@ ids. =back -=item C<get_enterable_products> B<UNSTABLE> +=item C<get_enterable_products> + +B<EXPERIMENTAL> =over @@ -132,7 +136,9 @@ ids. =back -=item C<get_accessible_products> B<UNSTABLE> +=item C<get_accessible_products> + +B<UNSTABLE> =over @@ -152,7 +158,9 @@ ids. =back -=item C<get> B<UNSTABLE> +=item C<get> + +B<EXPERIMENTAL> =over diff --git a/Bugzilla/WebService/User.pm b/Bugzilla/WebService/User.pm index 10537138c..24b9be709 100755 --- a/Bugzilla/WebService/User.pm +++ b/Bugzilla/WebService/User.pm @@ -238,14 +238,16 @@ log in/out using an existing account. =head1 METHODS -See L<Bugzilla::WebService> for a description of what B<STABLE>, B<UNSTABLE>, -and B<EXPERIMENTAL> mean, and for more information about error codes. +See L<Bugzilla::WebService> for a description of how parameters are passed, +and what B<STABLE>, B<UNSTABLE>, and B<EXPERIMENTAL> mean. =head2 Logging In and Out =over -=item C<login> B<EXPERIMENTAL> +=item C<login> + +B<STABLE> =over @@ -301,7 +303,9 @@ A login or password parameter was not provided. =back -=item C<logout> B<EXPERIMENTAL> +=item C<logout> + +B<STABLE> =over @@ -323,7 +327,9 @@ Log out the user. Does nothing if there is no user logged in. =over -=item C<offer_account_by_email> B<EXPERIMENTAL> +=item C<offer_account_by_email> + +B<STABLE> =over @@ -362,7 +368,9 @@ An account with that email address already exists in Bugzilla. =back -=item C<create> B<EXPERIMENTAL> +=item C<create> + +B<EXPERIMENTAL> =over @@ -373,6 +381,9 @@ Instead of this, you should use L</offer_account_by_email> when possible, because that makes sure that the email address specified can actually receive an email. This function does not check that. +You must be logged in and have the C<editusers> privilege in order to +call this function. + =item B<Params> =over @@ -423,7 +434,9 @@ password is over ten characters.) =over -=item C<get> B<UNSTABLE> +=item C<get> + +B<UNSTABLE> =over @@ -465,7 +478,9 @@ each string, which defaults to 1000 but can be changed by the Bugzilla administrator. Logged-out users cannot use this argument, and an error will be thrown -if they try. +if they try. (This is to make it harder for spammers to harvest email +addresses from Bugzilla, and also to enforce the user visibility +restrictions that are implemented on some Bugzillas.) =item C<include_fields> (array) @@ -564,6 +579,14 @@ function. =back +=item B<History> + +=over + +=item Added in Bugzilla B<3.4>. + +=back + =back =back diff --git a/Bugzilla/WebService/Util.pm b/Bugzilla/WebService/Util.pm index 16fea8c15..cd75bee8c 100644 --- a/Bugzilla/WebService/Util.pm +++ b/Bugzilla/WebService/Util.pm @@ -12,11 +12,12 @@ # # The Original Code is the Bugzilla Bug Tracking System. # -# The Initial Developer of the Original Code is Everything Solved. -# Portions created by Everything Solved are Copyright (C) 2008 -# Everything Solved. All Rights Reserved. +# The Initial Developer of the Original Code is Everything Solved, Inc. +# Portions created by the Initial Developer are Copyright (C) 2008 +# the Initial Developer. All Rights Reserved. # -# Contributor(s): Max Kanat-Alexander <mkanat@bugzilla.org> +# Contributor(s): +# Max Kanat-Alexander <mkanat@bugzilla.org> package Bugzilla::WebService::Util; use strict; @@ -48,7 +49,7 @@ __END__ =head1 NAME Bugzilla::WebService::Util - Utility functions used inside of the WebService -code. +code. These are B<not> functions that can be called via the WebService. =head1 DESCRIPTION |