1 files changed, 75 insertions, 5 deletions

diff --git a/Bugzilla/WebService.pm b/Bugzilla/WebService.pm
index 166707626..86fbe1fe3 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,37 @@ 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
+
+There are several shortcut identifiers to ask for only certain groups of
+fields to be returned or excluded.
+
+=over
+
+=item C<_all>
+
+All possible fields are returned if C<_all> is specified in C<include_fields>.
+
+=item C<_default>
+
+These fields are returned if C<include_fields> is empty or C<_default>
+is specified. All fields described in the documentation are returned
+by default unless specified otherwise.
+
+=item C<_extra>
+
+These fields are not returned by default and need to be manually specified
+in C<include_fields> either by field name, or using C<_extra>.
+
+=item C<_custom>
+
+Only custom fields are returned if C<_custom> is specified in C<include_fields>.
+This is normally specific to bug objects and not relevant for other returned
+objects.
+
 =back
 
 =head1 SEE ALSO