diff options
Diffstat (limited to 'Bugzilla/WebService.pm')
| -rw-r--r-- | Bugzilla/WebService.pm | 52 |
1 files changed, 47 insertions, 5 deletions
diff --git a/Bugzilla/WebService.pm b/Bugzilla/WebService.pm index 166707626..60642c5e8 100644 --- a/Bugzilla/WebService.pm +++ b/Bugzilla/WebService.pm @@ -52,15 +52,20 @@ This is the standard API for external programs that want to interact with Bugzilla. It provides various methods in various modules. You can interact with this API via -L<XML-RPC|Bugzilla::WebService::Server::XMLRPC> or -L<JSON-RPC|Bugzilla::WebService::Server::JSONRPC>. +L<XML-RPC|Bugzilla::WebService::Server::XMLRPC>, +L<JSON-RPC|Bugzilla::WebService::Server::JSONRPC> or +L<REST|Bugzilla::WebService::Server::REST>. =head1 CALLING METHODS -Methods are grouped into "packages", like C<Bug> for +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>. +For REST, the "package" is more determined by the path +used to access the resource. See each relevant method +for specific details on how to access via REST. + =head1 PARAMETERS The Bugzilla API takes the following various types of parameters: @@ -79,6 +84,11 @@ A floating-point number. May be null. A string. May be null. +=item C<email> + +A string representing an email address. This value, when returned, +may be filtered based on if the user is logged in or not. May be null. + =item C<dateTime> A date/time. Represented differently in different interfaces to this API. @@ -137,7 +147,7 @@ There are various ways to log in: =item C<User.login> -You can use L<Bugzilla::WebService::User/login> to log in as a Bugzilla +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 client must be capable of receiving and transmitting cookies. @@ -167,13 +177,24 @@ not expire. =back The C<Bugzilla_restrictlogin> and C<Bugzilla_rememberlogin> options -are only used when you have also specified C<Bugzilla_login> and +are only used when you have also specified C<Bugzilla_login> and C<Bugzilla_password>. Note that Bugzilla will return HTTP cookies along with the method response when you use these arguments (just like the C<User.login> method above). +For REST, you may also use the C<username> and C<password> variable +names instead of C<Bugzilla_login> and C<Bugzilla_password> as a +convenience. + +=item B<Added in Bugzilla 5.0> + +An error is now thrown if you pass invalid cookies or an invalid token. +You will need to log in again to get new cookies or a new token. Previous +releases simply ignored invalid cookies and token support was added in +Bugzilla B<5.0>. + =back =head1 STABLE, EXPERIMENTAL, and UNSTABLE @@ -258,6 +279,14 @@ be returned, the rest will not be included. If you specify an empty array, then this function will return empty hashes. +Some RPC calls support specifying sub fields. + +If an RPC call states that it support sub field restrictions, you can +restrict what information is returned within the first field. For example, +if you call Products.get with an include_fields of components.name, then +only the component name would be returned (and nothing else). You can +include the main field, and exclude a sub field. + Invalid field names are ignored. Example: @@ -268,6 +297,9 @@ would return something like: { users => [{ id => 1, name => 'user@domain.com' }] } +Note for REST, C<include_fields> may instead be a comma delimited string +for GET type requests. + =item C<exclude_fields> C<array> An array of strings, representing the (case-sensitive) names of @@ -277,6 +309,13 @@ the returned hashes. If you specify all the fields, then this function will return empty hashes. +Some RPC calls support specifying sub fields. If an RPC call states that +it support sub field restrictions, you can restrict what information is +returned within the first field. For example, if you call Products.get +with an include_fields of components.name, then only the component name +would be returned (and nothing else). You can include the main field, +and exclude a sub field. + Invalid field names are ignored. Specifying fields here overrides C<include_fields>, so if you specify a @@ -290,6 +329,9 @@ would return something like: { users => [{ id => 1, real_name => 'John Smith' }] } +Note for REST, C<exclude_fields> may instead be a comma delimited string +for GET type requests. + =back =head1 SEE ALSO |