From 384d1d254d14bafc3fdf62a08668c6cb36249563 Mon Sep 17 00:00:00 2001
From: Dave Lawrence <dlawrence@mozilla.com>
Date: Fri, 12 Jul 2013 16:39:50 -0400
Subject: Bug 866927 - Enhance Bugzilla WebServices to allow data access using
 REST r=glob,a=justdave

---
 Bugzilla/WebService/Bugzilla.pm | 74 ++++++++++++++++++++++++++++++++++++-----
 1 file changed, 66 insertions(+), 8 deletions(-)

(limited to 'Bugzilla/WebService/Bugzilla.pm')

diff --git a/Bugzilla/WebService/Bugzilla.pm b/Bugzilla/WebService/Bugzilla.pm
index 6fd7a023a..10ba38bab 100644
--- a/Bugzilla/WebService/Bugzilla.pm
+++ b/Bugzilla/WebService/Bugzilla.pm
@@ -121,12 +121,12 @@ sub time {
 sub last_audit_time {
     my ($self, $params) = validate(@_, 'class');
     my $dbh = Bugzilla->dbh;
-    
+
     my $sql_statement = "SELECT MAX(at_time) FROM audit_log";
     my $class_values =  $params->{class};
     my @class_values_quoted;
     foreach my $class_value (@$class_values) {
-        push (@class_values_quoted, $dbh->quote($class_value)) 
+        push (@class_values_quoted, $dbh->quote($class_value))
             if $class_value =~ /^Bugzilla(::[a-zA-Z0-9_]+)*$/;
     }
 
@@ -135,11 +135,11 @@ sub last_audit_time {
     }
 
     my $last_audit_time = $dbh->selectrow_array("$sql_statement");
- 
+
     # All Webservices return times in UTC; Use UTC here for backwards compat.
     # Hardcode values where appropriate
     $last_audit_time = datetime_from($last_audit_time, 'UTC');
-    
+
     return {
         last_audit_time => $self->type('dateTime', $last_audit_time)
     };
@@ -181,6 +181,10 @@ This provides functions that tell you about Bugzilla in general.
 See L<Bugzilla::WebService> for a description of how parameters are passed,
 and what B<STABLE>, B<UNSTABLE>, and B<EXPERIMENTAL> mean.
 
+Although the data input and output is the same for JSONRPC, XMLRPC and REST,
+the directions for how to access the data via REST is noted in each method
+where applicable.
+
 =head2 version
 
 B<STABLE>
@@ -191,6 +195,12 @@ B<STABLE>
 
 Returns the current version of Bugzilla.
 
+=item B<REST>
+
+GET /version
+
+The returned data format is the same as below.
+
 =item B<Params> (none)
 
 =item B<Returns>
@@ -200,6 +210,14 @@ string.
 
 =item B<Errors> (none)
 
+=item B<History>
+
+=over
+
+=item REST API call added in Bugzilla B<5.0>.
+
+=back
+
 =back
 
 =head2 extensions
@@ -213,6 +231,12 @@ B<EXPERIMENTAL>
 Gets information about the extensions that are currently installed and enabled
 in this Bugzilla.
 
+=item B<REST>
+
+GET /extensions
+
+The returned data format is the same as below.
+
 =item B<Params> (none)
 
 =item B<Returns>
@@ -243,6 +267,8 @@ The return value looks something like this:
 that the extensions define themselves. Before 3.6, the names of the
 extensions depended on the directory they were in on the Bugzilla server.
 
+=item REST API call added in Bugzilla B<5.0>.
+
 =back
 
 =back
@@ -258,6 +284,12 @@ Use L</time> instead.
 
 Returns the timezone that Bugzilla expects dates and times in.
 
+=item B<REST>
+
+GET /timezone
+
+The returned data format is the same as below.
+
 =item B<Params> (none)
 
 =item B<Returns>
@@ -272,6 +304,8 @@ string in (+/-)XXXX (RFC 2822) format.
 =item As of Bugzilla B<3.6>, the timezone returned is always C<+0000>
 (the UTC timezone).
 
+=item REST API call added in Bugzilla B<5.0>.
+
 =back
 
 =back
@@ -288,6 +322,12 @@ B<STABLE>
 Gets information about what time the Bugzilla server thinks it is, and
 what timezone it's running in.
 
+=item B<REST>
+
+GET /time
+
+The returned data format is the same as below.
+
 =item B<Params> (none)
 
 =item B<Returns>
@@ -298,7 +338,7 @@ A struct with the following items:
 
 =item C<db_time>
 
-C<dateTime> The current time in UTC, according to the Bugzilla 
+C<dateTime> The current time in UTC, according to the Bugzilla
 I<database server>.
 
 Note that Bugzilla assumes that the database and the webserver are running
@@ -308,7 +348,7 @@ rely on for doing searches and other input to the WebService.
 
 =item C<web_time>
 
-C<dateTime> This is the current time in UTC, according to Bugzilla's 
+C<dateTime> This is the current time in UTC, according to Bugzilla's
 I<web server>.
 
 This might be different by a second from C<db_time> since this comes from
@@ -324,7 +364,7 @@ versions of Bugzilla before 3.6.)
 =item C<tz_name>
 
 C<string> The literal string C<UTC>. (Exists only for backwards-compatibility
-with versions of Bugzilla before 3.6.) 
+with versions of Bugzilla before 3.6.)
 
 =item C<tz_short_name>
 
@@ -348,6 +388,8 @@ with versions of Bugzilla before 3.6.)
 were in the UTC timezone, instead of returning information in the server's
 local timezone.
 
+=item REST API call added in Bugzilla B<5.0>.
+
 =back
 
 =back
@@ -362,6 +404,12 @@ B<UNSTABLE>
 
 Returns parameter values currently used in this Bugzilla.
 
+=item B<REST>
+
+GET /parameters
+
+The returned data format is the same as below.
+
 =item B<Params> (none)
 
 =item B<Returns>
@@ -419,6 +467,8 @@ never be stable.
 
 =item Added in Bugzilla B<4.4>.
 
+=item REST API call added in Bugzilla B<5.0>.
+
 =back
 
 =back
@@ -433,9 +483,15 @@ B<EXPERIMENTAL>
 
 Gets the latest time of the audit_log table.
 
+=item B<REST>
+
+GET /last_audit_time
+
+The returned data format is the same as below.
+
 =item B<Params>
 
-You can pass the optional parameter C<class> to get the maximum for only 
+You can pass the optional parameter C<class> to get the maximum for only
 the listed classes.
 
 =over
@@ -460,6 +516,8 @@ at_time from the audit_log.
 
 =item Added in Bugzilla B<4.4>.
 
+=item REST API call added in Bugzilla B<5.0>.
+
 =back
 
 =back
-- 
cgit v1.2.3-24-g4f1b