Bug 1038275: Comprehensible documentation for the REST API

Bugzilla/Install/Requirements.pm

@@ -396,6 +396,14 @@ sub OPTIONAL_MODULES {
         version => '0',
         feature => ['memcached'],
     },
+
+    # Documentation
+    {
+        package => 'File-Copy-Recursive',
+        module  => 'File::Copy::Recursive',
+        version => 0,
+        feature => ['documentation'],
+    }
     );
 
     my $extra_modules = _get_extension_requirements('OPTIONAL_MODULES');

docs/en/rst/api.rst

+WebService API
+==============
+
+This Bugzilla installation has the following WebService APIs available
+(as of the last time you compiled the documentation):
+
+.. toctree::
+   :glob:
+
+   api/core/v*/index*
+   api/extensions/*/v*/index*

docs/en/rst/api/core/v1/bug-user-last-visit.rst

+Bug User Last Visited
+=====================
+
+.. _rest-bug-user-last-visit-update:
+
+Update Last Visited
+-------------------
+
+Update the last-visited time for the specified bug and current user.
+
+**Request**
+
+To update the time for a single bug id:
+
+.. code-block:: text
+
+   POST /rest/bug_user_last_visit/(id)
+
+To update one or more bug ids at once:
+
+.. code-block:: text
+
+   POST /rest/bug_user_last_visit
+
+.. code-block:: js
+
+   {
+     "ids" : [35,36,37]
+   }
+
+=======  =====  ==============================
+name     type   description
+=======  =====  ==============================
+**id**   int    An integer bug id.
+**ids**  array  One or more bug ids to update.
+=======  =====  ==============================
+
+**Response**
+
+.. code-block:: js
+
+   [
+     {
+       "id" : 100,
+       "last_visit_ts" : "2014-10-16T17:38:24Z"
+     }
+   ]
+
+An array of objects containing the items:
+
+=============  ========  ============================================
+name           type      description
+=============  ========  ============================================
+id             int       The bug id.
+last_visit_ts  datetime  The timestamp the user last visited the bug.
+=============  ========  ============================================
+
+.. _rest-bug-user-last-visit-get:
+
+Get Last Visited
+----------------
+
+**Request**
+
+Get the last-visited timestamp for one or more specified bug ids or get a
+list of the last 20 visited bugs and their timestamps.
+
+To return the last-visited timestamp for a single bug id:
+
+.. code-block:: text
+
+   GET /rest/bug_user_last_visit/(id)
+
+To return more than one specific bug timestamps:
+
+.. code-block:: text
+
+   GET /rest/bug_user_last_visit/123?ids=234&ids=456
+
+To return just the most recent 20 timestamps:
+
+.. code-block:: text
+
+   GET /rest/bug_user_last_visit
+
+=======  =====  ============================================
+name     type   description
+=======  =====  ============================================
+**id**   int    An integer bug id.
+**ids**  array  One or more optional bug ids to get.
+=======  =====  ============================================
+
+**Response**
+
+.. code-block:: js
+
+   [
+     {
+       "id" : 100,
+       "last_visit_ts" : "2014-10-16T17:38:24Z"
+     }
+   ]
+
+An array of objects containing the following items:
+
+=============  ========  ============================================
+name           type      description
+=============  ========  ============================================
+id             int       The bug id.
+last_visit_ts  datetime  The timestamp the user last visited the bug.
+=============  ========  ============================================

docs/en/rst/api/core/v1/bugzilla.rst

+Bugzilla Information
+====================
+
+These methods are used to get general configuration information about this
+Bugzilla instance.
+
+Version
+-------
+
+Returns the current version of Bugzilla. Normally in the format of ``X.X`` or
+``X.X.X``. For example, ``4.4`` for the initial release of a new branch. Or
+``4.4.6`` for a minor release on the same branch.
+
+**Request**
+
+.. code-block:: text
+
+   GET /rest/version
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "version": "4.5.5+"
+   }
+
+=======  ======  =========================================
+name     type    description
+=======  ======  =========================================
+version  string  The current version of this Bugzilla
+=======  ======  =========================================
+
+Extensions
+----------
+
+Gets information about the extensions that are currently installed and enabled
+in this Bugzilla.
+
+**Request**
+
+.. code-block:: text
+
+   GET /rest/extensions
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "extensions": {
+       "Voting": {
+         "version": "4.5.5+"
+       },
+       "BmpConvert": {
+         "version": "1.0"
+       }
+     }
+   }
+
+==========  ======  ====================================================
+name        type    description
+==========  ======  ====================================================
+extensions  object  An object containing the extensions enabled as keys.
+                    Each extension object contains the following keys:
+
+                    * ``version`` (string) The version of the extension.
+==========  ======  ====================================================
+
+Timezone
+--------
+
+Returns the timezone in which Bugzilla expects to receive dates and times on the API.
+Currently hard-coded to UTC ("+0000"). This is unlikely to change.
+
+**Request**
+
+.. code-block:: text
+
+   GET /rest/timezone
+
+.. code-block:: js
+
+   {
+     "timezone": "+0000"
+   }
+
+**Response**
+
+========  ======  ===============================================================
+name      type    description
+========  ======  ===============================================================
+timezone  string  The timezone offset as a string in (+/-)XXXX (RFC 2822) format.
+========  ======  ===============================================================
+
+Time
+----
+
+Gets information about what time the Bugzilla server thinks it is, and
+what timezone it's running in.
+
+**Request**
+
+.. code-block:: text
+
+   GET /rest/time
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "web_time_utc": "2014-09-26T18:01:30Z",
+     "db_time": "2014-09-26T18:01:30Z",
+     "web_time": "2014-09-26T18:01:30Z",
+     "tz_offset": "+0000",
+     "tz_short_name": "UTC",
+     "tz_name": "UTC"
+   }
+
+=============  ======  ==========================================================
+name           type    description
+=============  ======  ==========================================================
+db_time        string  The current time in UTC, according to the Bugzilla
+                       database server.
+
+                       Note that Bugzilla assumes that the database and the
+                       webserver are running in the same time zone. However,
+                       if the web server and the database server aren't
+                       synchronized or some reason, *this* is the time that
+                       you should rely on or doing searches and other input
+                       to the WebService.
+web_time       string  This is the current time in UTC, according to
+                       Bugzilla's web server.
+
+                       This might be different by a second from ``db_time``
+                       since this comes from a different source. If it's any
+                       more different than a second, then there is likely
+                       some problem with this Bugzilla instance. In this
+                       case you should rely  on the ``db_time``, not the
+                       ``web_time``.
+web_time_utc   string  Identical to ``web_time``. (Exists only for
+                       backwards-compatibility with versions of Bugzilla
+                       before 3.6.)
+tz_name        string  The literal string ``UTC``. (Exists only for
+                       backwards-compatibility with versions of Bugzilla
+                       before 3.6.)
+tz_short_name  string  The literal string ``UTC``. (Exists only for
+                       backwards-compatibility with versions of Bugzilla
+                       before 3.6.)
+tz_offset      string  The literal string ``+0000``. (Exists only for
+                       backwards-compatibility with versions of Bugzilla
+                       before 3.6.)
+=============  ======  ==========================================================
+
+Parameters
+----------
+
+Returns parameter values currently used in this Bugzilla.
+
+**Request**
+
+.. code-block:: text
+
+   GET /rest/parameters
+
+**Response**
+
+Example response for anonymous user:
+
+.. code-block:: js
+
+   {
+      "parameters" : {
+         "maintainer" : "admin@example.com",
+         "requirelogin" : "0"
+      }
+   }
+
+Example response for authenticated user:
+
+.. code-block:: js
+
+   {
+      "parameters" : {
+          "allowemailchange" : "1",
+          "attachment_base" : "http://bugzilla.example.com/",
+          "commentonchange_resolution" : "0",
+          "commentonduplicate" : "0",
+          "cookiepath" : "/",
+          "createemailregexp" : ".*",
+          "defaultopsys" : "",
+          "defaultplatform" : "",
+          "defaultpriority" : "--",
+          "defaultseverity" : "normal",
+          "duplicate_or_move_bug_status" : "RESOLVED",
+          "emailregexp" : "^[\\w\\.\\+\\-=']+@[\\w\\.\\-]+\\.[\\w\\-]+$",
+          "emailsuffix" : "",
+          "letsubmitterchoosemilestone" : "1",
+          "letsubmitterchoosepriority" : "1",
+          "mailfrom" : "bugzilla-daemon@example.com",
+          "maintainer" : "admin@example.com",
+          "maxattachmentsize" : "1000",
+          "maxlocalattachment" : "0",
+          "musthavemilestoneonaccept" : "0",
+          "noresolveonopenblockers" : "0",
+          "password_complexity" : "no_constraints",
+          "rememberlogin" : "on",
+          "requirelogin" : "0",
+          "urlbase" : "http://bugzilla.example.com/",
+          "use_see_also" : "1",
+          "useclassification" : "1",
+          "usemenuforusers" : "0",
+          "useqacontact" : "1",
+          "usestatuswhiteboard" : "1",
+          "usetargetmilestone" : "1",
+      }
+   }
+
+A logged-out user can only access the ``maintainer`` and ``requirelogin``
+parameters.
+
+A logged-in user can access the following parameters (listed alphabetically):
+
+* allowemailchange
+* attachment_base
+* commentonchange_resolution
+* commentonduplicate
+* cookiepath
+* defaultopsys
+* defaultplatform
+* defaultpriority
+* defaultseverity
+* duplicate_or_move_bug_status
+* emailregexpdesc
+* emailsuffix
+* letsubmitterchoosemilestone
+* letsubmitterchoosepriority
+* mailfrom
+* maintainer
+* maxattachmentsize
+* maxlocalattachment
+* musthavemilestoneonaccept
+* noresolveonopenblockers
+* password_complexity
+* rememberlogin
+* requirelogin
+* search_allow_no_criteria
+* urlbase
+* use_see_also
+* useclassification
+* usemenuforusers
+* useqacontact
+* usestatuswhiteboard
+* usetargetmilestone
+
+A user in the tweakparams group can access all existing parameters.
+New parameters can appear or obsolete parameters can disappear depending
+on the version of Bugzilla and on extensions being installed.
+The list of parameters returned by this method is not stable and will
+never be stable.
+
+Last Audit Time
+---------------
+
+Gets the most recent timestamp among all of the events recorded in the audit_log
+table.
+
+**Request**
+
+To get most recent audit timestamp for all classes:
+
+.. code-block:: text
+
+   GET /rest/last_audit_time
+
+To get the the most recent audit timestamp for the ``Bugzilla::Product`` class:
+
+.. code-block:: text
+
+   GET /rest/last_audit_time?class=Bugzilla::Product
+
+=====  =====  ===================================================================
+name   type   description
+=====  =====  ===================================================================
+class  array  The class names are defined as ``Bugzilla::<class_name>"`` such as
+              Bugzilla:Product`` for products.
+=====  =====  ===================================================================
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "last_audit_time": "2014-09-23T18:03:38Z"
+   }
+
+===============  ======  ====================================================
+name             type    description
+===============  ======  ====================================================
+last_audit_time  string  The maximum of the at_time from the audit_log.
+===============  ======  ====================================================

docs/en/rst/api/core/v1/classification.rst

+Classifications
+===============
+
+This part of the Bugzilla API allows you to deal with the available
+classifications. You will be able to get information about them as well as
+manipulate them.
+
+.. _rest_get_classification:
+
+Get Classification
+------------------
+
+Returns an object containing information about a set of classifications.
+
+**Request**
+
+To return information on a single classification using the ID or name:
+
+.. code-block:: text
+
+   GET /rest/classification/(id_or_name)
+
+==============  =====  =====================================
+name            type   description
+==============  =====  =====================================
+**id_or_name**  mixed  An Integer classification ID or name.
+==============  =====  =====================================
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "classifications": [
+       {
+         "sort_key": 0,
+         "description": "Unassigned to any classifications",
+         "products": [
+           {
+             "id": 2,
+             "name": "FoodReplicator",
+             "description": "Software that controls a piece of hardware that will create any food item through a voice interface."
+           },
+           {
+             "description": "Spider secretions",
+             "name": "Ѕpїdєr Séçretíøns",
+             "id": 4
+           }
+         ],
+         "id": 1,
+         "name": "Unclassified"
+       }
+     ]
+   }
+
+``classifications`` (array) Each object is a classification that the user is
+authorized to see and has the following items:
+
+===========  ======  ============================================================
+name         type    description
+===========  ======  ============================================================
+id           int     The ID of the classification.
+name         string  The name of the classification.
+description  string  The description of the classificaion.
+sort_key     int     The value which determines the order the classification is
+                     sorted.
+products     array   Products the user is authorized to
+                     access within the classification. Each hash has the
+                     following keys:
+===========  ======  ============================================================
+
+Product object:
+
+===========  ======  ================================
+name         type    description
+===========  ======  ================================
+name         string  The name of the product.
+id           int     The ID of the product.
+description  string  The description of the product.
+===========  ======  ================================

docs/en/rst/api/core/v1/comment.rst

+Comments
+========
+
+.. _rest_comments:
+
+Get Comments
+------------
+
+This allows you to get data about comments, given a bug ID or comment ID.
+
+**Request**
+
+To get all comments for a particular bug using the bug ID or alias:
+
+.. code-block:: text
+
+   GET /rest/bug/(id_or_alias)/comment
+
+To get a specific comment based on the comment ID:
+
+.. code-block:: text
+
+   GET /rest/bug/comment/(comment_id)
+
+===============  ========  ======================================================
+name             type      description
+===============  ========  ======================================================
+**id_or_alias**  mixed     A single integer bug ID or alias.
+**comment_id**   int       A single integer comment ID.
+new_since        datetime  If specified, the method will only return comments
+                           *newer* than this time. This only affects comments
+                           returned from the ``ids`` argument. You will always be
+                           returned all comments you request in the
+                           ``comment_ids`` argument, even if they are older than
+                           this date.
+===============  ========  ======================================================
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "bugs": {
+       "35": {
+         "comments": [
+           {
+             "time": "2000-07-25T13:50:04Z",
+             "text": "test bug to fix problem in removing from cc list.",
+             "bug_id": 35,
+             "count": 0,
+             "attachment_id": null,
+             "is_private": false,
+             "tags": [],
+             "creator": "user@bugzilla.org",
+             "creation_time": "2000-07-25T13:50:04Z",
+             "id": 75
+           }
+         ]
+       }
+     },
+     "comments": {}
+   }
+
+Two items are returned:
+
+``bugs`` This is used for bugs specified in ``ids``. This is an object,
+where the keys are the numeric IDs of the bugs, and the value is
+a object with a single key, ``comments``, which is an array of comments.
+(The format of comments is described below.)
+
+Any individual bug will only be returned once, so if you specify an ID
+multiple times in ``ids``, it will still only be returned once.
+
+``comments`` Each individual comment requested in ``comment_ids`` is
+returned here, in a object where the numeric comment ID is the key,
+and the value is the comment. (The format of comments is described below.)
+
+A "comment" as described above is a object that contains the following items:
+
+=============  ========  ========================================================
+name           type      description
+=============  ========  ========================================================
+id             int       The globally unique ID for the comment.
+bug_id         int       The ID of the bug that this comment is on.
+attachment_id  int       If the comment was made on an attachment, this will be
+                         the ID of that attachment. Otherwise it will be null.
+count          int       The number of the comment local to the bug. The
+                         Description is 0, comments start with 1.
+text           string    The actual text of the comment.
+creator        string    The login name of the comment's author.
+time           datetime  The time (in Bugzilla's timezone) that the comment was
+                         added.
+creation_time  datetime  This is exactly same as the ``time`` key. Use this
+                         field instead of ``time`` for consistency with other
+                         methods including :ref:`rest_single_bug` and
+                         :ref:`rest_attachments`.
+
+                         For compatibility, ``time`` is still usable. However,
+                         please note that ``time`` may be deprecated and removed
+                         in a future release.
+
+is_private     boolean   ``true`` if this comment is private (only visible to a
+                         certain group called the "insidergroup"), ``false``
+                         otherwise.
+=============  ========  ========================================================
+
+.. _rest_add_comment:
+
+Create Comments
+---------------
+
+This allows you to add a comment to a bug in Bugzilla.
+
+**Request**
+
+To create a comment on a current bug.
+
+.. code-block:: text
+
+   POST /rest/bug/(id)/comment
+
+.. code-block:: js
+
+   {
+     "ids" : [123,..],
+     "comment" : "This is an additional comment",
+     "is_private" : false
+   }
+
+``ids`` is optional in the data example above and can be used to specify adding
+a comment to more than one bug at the same time.
+
+===========  =======  ===========================================================
+name         type     description
+===========  =======  ===========================================================
+**id**       int      The ID or alias of the bug to append a comment to.
+ids          array    List of integer bug IDs to add the comment to.
+**comment**  string   The comment to append to the bug. If this is empty
+                      or all whitespace, an error will be thrown saying that you
+                      did not set the ``comment`` parameter.
+is_private   boolean  If set to true, the comment is private, otherwise it is
+                      assumed to be public.
+work_time    double   Adds this many hours to the "Hours Worked" on the bug.
+                      If you are not in the time tracking group, this value will
+                      be ignored.
+===========  =======  ===========================================================
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "id" : 789
+   }
+
+====  ====  =================================
+name  type  description
+====  ====  =================================
+id    int   ID of the newly-created comment.
+====  ====  =================================
+
+.. _rest_search_comment_tags:
+
+Search Comment Tags
+-------------------
+
+Searches for tags which contain the provided substring.
+
+**Request**
+
+To search for comment tags:
+
+.. code-block:: text
+
+   GET /rest/bug/comment/tags/(query)
+
+Example:
+
+.. code-block:: text
+
+   GET /rest/bug/comment/tags/spa
+
+=========  ======  ====================================================
+name       type    description
+=========  ======  ====================================================
+**query**  string  Only tags containg this substring will be returned.
+limit      int     If provided will return no more than ``limit`` tags.
+                   Defaults to ``10``.
+=========  ======  ====================================================
+
+**Response**
+
+.. code-block:: js
+
+   [
+     "spam"
+   ]
+
+An array of matching tags.
+
+.. _rest_update_comment_tags:
+
+Update Comment Tags
+-------------------
+
+Adds or removes tags from a comment.
+
+**Request**
+
+To update the tags comments attached to a comment:
+
+.. code-block:: text
+
+   PUT /rest/bug/comment/(comment_id)/tags
+
+Example:
+
+.. code-block:: js
+
+   {
+     "comment_id" : 75,
+     "add" : ["spam", "bad"]
+   }
+
+==============  =====  ====================================
+name            type   description
+==============  =====  ====================================
+**comment_id**  int    The ID of the comment to update.
+add             array  The tags to attach to the comment.
+remove          array  The tags to detach from the comment.
+==============  =====  ====================================
+
+**Response**
+
+.. code-block:: js
+
+   [
+     "bad",
+     "spam"
+   ]
+
+An array of strings containing the comment's updated tags.

docs/en/rst/api/core/v1/component.rst

+Components
+==========
+
+This part of the Bugzilla API allows you to deal with the available product
+components. You will be able to get information about them as well as manipulate
+them.
+
+Create Component
+----------------
+
+This allows you to create a new component in Bugzilla. You must be authenticated
+and be in the *editcomponents* group to perform this action.
+
+**Request**
+
+To create a new component:
+
+.. code-block:: text
+
+   POST /rest/component
+
+.. code-block:: js
+
+   {
+     "product" : "TestProduct",
+     "name" : "New Component",
+     "description" : "This is a new component",
+     "default_assignee" : "dkl@mozilla.com"
+   }
+
+Some params must be set, or an error will be thrown. These params are
+shown in **bold**.
+
+====================  =======  ==================================================
+name                  type     description
+====================  =======  ==================================================
+**name**              string   The name of the new component.
+**product**           string   The name of the product that the component must
+                               be added to. This product must already exist, and
+                               the user have the necessary permissions to edit
+                               components for it.
+**description**       string   The description of the new component.
+**default_assignee**  string   The login name of the default assignee of the
+                               component.
+default_cc            array    Each string representing one login name of the
+                               default CC list.
+default_qa_contact    string   The login name of the default QA contact for the
+                               component.
+is_open               boolean  1 if you want to enable the component for bug
+                               creations. 0 otherwise. Default is 1.
+====================  =======  ==================================================
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "id": 27
+   }
+
+====  ====  ========================================
+name  type  description
+====  ====  ========================================
+id    int   The ID of the newly-added component.
+====  ====  ========================================

docs/en/rst/api/core/v1/field.rst

+Bug Fields
+==========
+
+The Bugzilla API for getting details about bug fields.
+
+.. _rest_fields:
+
+Fields
+------
+
+Get information about valid bug fields, including the lists of legal values
+for each field.
+
+**Request**
+
+To get information about all fields:
+
+.. code-block:: text
+
+   GET /rest/field/bug
+
+To get information related to a single field:
+
+.. code-block:: text
+
+   GET /rest/field/bug/(id_or_name)
+
+==========  =====  ==========================================================
+name        type   description
+==========  =====  ==========================================================
+id_or_name  mixed  An integer field ID or string representing the field name.
+==========  =====  ==========================================================
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "fields": [
+       {
+         "display_name": "Priority",
+         "name": "priority",
+         "type": 2,
+         "is_mandatory": false,
+         "value_field": null,
+         "values": [
+           {
+             "sortkey": 100,
+             "sort_key": 100,
+             "visibility_values": [],
+             "name": "P1"
+           },
+           {
+             "sort_key": 200,
+             "name": "P2",
+             "visibility_values": [],
+             "sortkey": 200
+           },
+           {
+             "sort_key": 300,
+             "visibility_values": [],
+             "name": "P3",
+             "sortkey": 300
+           },
+           {
+             "sort_key": 400,
+             "name": "P4",
+             "visibility_values": [],
+             "sortkey": 400
+           },
+           {
+             "name": "P5",
+             "visibility_values": [],
+             "sort_key": 500,
+             "sortkey": 500
+           }
+         ],
+         "visibility_values": [],
+         "visibility_field": null,
+         "is_on_bug_entry": false,
+         "is_custom": false,
+         "id": 13
+       }
+     ]
+   }
+
+``field`` (array) Field objects each containing the following items:
+
+=================  =======  =====================================================
+name               type     description
+=================  =======  =====================================================
+id                 int      An integer ID uniquely identifying this field in this
+                            installation only.
+type               int      The number of the fieldtype. The following values are
+                            defined:
+
+                            * ``0`` Field type unknown
+                            * ``1`` Single-line string field
+                            * ``2`` Single value field
+                            * ``3`` Multiple value field
+                            * ``4`` Multi-line text value
+                            * ``5`` Date field with time
+                            * ``6`` Bug ID field
+                            * ``7`` See Also field
+                            * ``8`` Keywords field
+                            * ``9`` Date field
+                            * ``10`` Integer field
+
+is_custom          boolean  ``true`` when this is a custom field, ``false``
+                            otherwise.
+name               string   The internal name of this field. This is a unique
+                            identifier for this field. If this is not a custom
+                            field, then this name will be the same across all
+                            Bugzilla installations.
+display_name       string   The name of the field, as it is shown in the user
+                            interface.
+is_mandatory       boolean  ``true`` if the field must have a value when filing
+                            new bugs. Also, mandatory fields cannot have their
+                            value cleared when updating bugs.
+is_on_bug_entry    boolean  For custom fields, this is ``true`` if the field is
+                            shown when you enter a new bug. For standard fields,
+                            this is currently always ``false``, even if the field
+                            shows up when entering a bug. (To know whether or not
+                            a standard field is valid on bug entry, see
+                            :ref:`rest_create_bug`.
+visibility_field   string   The name of a field that controls the visibility of
+                            this field in the user interface. This field only
+                            appears in the user interface when the named field is
+                            equal to one of the values is ``visibility_values``.
+                            Can be null.
+visibility_values  array    This field is only shown when ``visibility_field``
+                            matches one of these string values. When
+                            ``visibility_field`` is null, then this is an empty
+                            array.
+value_field        string   The name of the field that controls whether or not
+                            particular values of the field are shown in the user
+                            interface. Can be null.
+values             array    Objects representing the legal values for
+                            select-type (drop-down and multiple-selection)
+                            fields. This is  also populated for the
+                            ``component``, ``version``, ``target_milestone``,
+                            and ``keywords`` fields, but not for the ``product``
+                            field (you must use ``get_accessible_products`` for
+                            that). For fields that aren't select-type fields,
+                            this will simply be an empty array. Each object
+                            contains the items described in the Value object
+                            below.
+=================  =======  =====================================================
+
+Value object:
+
+=================  =======  =====================================================
+name               type     description
+=================  =======  =====================================================
+name               string   The actual value--this is what you would specify for
+                            this field in ``create``, etc.
+sort_key           int      Values, when displayed in a list, are sorted first by
+                            this integer and then secondly by their name.
+visibility_values  array    If ``value_field`` is defined for this field, then
+                            this value is only shown if the ``value_field`` is
+                            set to one of the values listed in this array. Note
+                            that for per-product fields, ``value_field`` is set
+                            to ``product`` and ``visibility_values`` will reflect
+                            which product(s) this value appears in.
+is_active          boolean  This value is defined only for certain
+                            product-specific fields such as version,
+                            target_milestone or component. When true, the value
+                            is active; otherwise the value is not active.
+description        string   The description of the value. This item is only
+                            included for the ``keywords`` field.
+is_open            boolean  For ``bug_status`` values, determines whether this
+                            status specifies that the bug is "open" (``true``)
+                            or "closed" (``false``). This item is only included
+                            for the ``bug_status`` field.
+can_change_to      array    For ``bug_status`` values, this is an array of
+                            objects that determine which statuses you can
+                            transition to from this status. (This item is only
+                            included for the ``bug_status`` field.)
+
+                            Each object contains the following items:
+
+                            * name: (string) The name of the new status
+                            * comment_required: (boolean) ``true`` if a comment
+                              is required when you change a bug into this status
+                              using this transition.
+=================  =======  =====================================================
+
+.. _rest_legal_values:
+
+Legal Values
+------------
+
+**DEPRECATED** Use ''Fields'' instead.
+
+Tells you what values are allowed for a particular field.
+
+**Request**
+
+To get information on the values for a field based on field name:
+
+.. code-block:: text
+
+   GET /rest/field/bug/(field)/values
+
+To get information based on field name and a specific product:
+
+.. code-block:: text
+
+   GET /rest/field/bug/(field)/(product_id)/values
+
+==========  ======  =============================================================
+name        type    description
+==========  ======  =============================================================
+field       string  The name of the field you want information about.
+                    This should be the same as the name you would use in
+                    :ref:`rest_create_bug`, below.
+product_id  int     If you're picking a product-specific field, you have to
+                    specify the ID of the product you want the values for.
+==========  ======  =============================================================
+
+**Resppnse**
+
+.. code-block:: js
+
+   {
+     "values": [
+       "P1",
+       "P2",
+       "P3",
+       "P4",
+       "P5"
+     ]
+   }
+
+==========  ======  =============================================================
+name        type    description
+==========  ======  =============================================================
+values      array   The legal values for this field. The values will be sorted
+                    as they normally would be in Bugzilla.
+==========  ======  =============================================================

docs/en/rst/api/core/v1/general.rst

+General
+=======
+
+This is the standard REST API for external programs that want to interact
+with Bugzilla. It provides a REST interface to various Bugzilla functions.
+
+Basic Information
+-----------------
+
+**Browsing**
+
+If the ``Accept`` header of a request is set to ``text/html`` (as it is by an
+ordinary web browser) then the API will return the JSON data as a HTML
+page which the browser can display. In other words, you can play with the
+API using just your browser to see results in a human-readable form.
+This is a good way to try out the various GET calls, even if you can't use
+it for POST or PUT.
+
+**Data Format**
+
+The REST API only supports JSON input, and either JSON or JSONP output.
+So objects sent and received must be in JSON format.
+
+On every request, you must set both the ``Accept`` and ``Content-Type`` HTTP
+headers to the MIME type of the data format you are using to communicate with
+the API. ``Content-Type`` tells the API how to interpret your request, and
+``Accept`` tells it how you want your data back. ``Content-Type`` must be
+``application/json``. ``Accept`` can be either that, or
+``application/javascript`` for JSONP. In the latter`case, add a ``callback``
+parameter to name your callback.
+
+Parameters may also be passed in as part of the query string for non-GET
+requests and will override any matching parameters in the request body.
+
+Example request which returns the current version of Bugzilla:
+
+.. code-block:: http
+
+   GET /rest/version HTTP/1.1
+   Host: bugzilla.example.com
+   Accept: application/json
+
+Example response:
+
+.. code-block:: http
+
+   HTTP/1.1 200 OK
+   Vary: Accept
+   Content-Type: application/json
+
+   {
+     "version" : "4.2.9+"
+   }
+
+**Errors**
+
+When an error occurs over REST, an object is returned with the key ``error``
+set to ``true``.
+
+The error contents look similar to:
+
+.. code-block:: js
+
+   {
+     "error": true,
+     "message": "Some message here",
+     "code": 123
+   }
+
+Common Data Types
+-----------------
+
+The Bugzilla API uses the following various types of parameters:
+
+========  ======================================================================
+ type     description
+========  ======================================================================
+int       Integer.
+double    A floating-point number.
+string    A string.
+email     A string representing an email address. This value, when returned,
+          may be filtered based on if the user is logged in or not.
+date      A specific date. Example format: ``YYYY-MM-DD``.
+datetime  A date/time. Timezone should be in UTC unless otherwise noted.
+          Example format: ``YYYY-MM-DDTHH24:MI:SSZ``.
+boolean   ``true`` or ``false``.
+base64    A base64-encoded string. This is the only way to transfer
+          binary data via the API.
+array     An array. There may be mixed types in an array. ``[`` and ``]`` are
+          used to represent the beginning and end of arrays.
+object    A mapping of keys to values. Called a "hash", "dict", or "map" in
+          some other programming languages. The keys are strings, and the
+          values can be any type. ``{`` and ``}`` are used to represent the
+          beginning and end of objects.
+========  ======================================================================
+
+Parameters that are required will be displayed in **bold** in the parameters
+table for each API method.
+
+Authentication
+--------------
+
+Some methods do not require you to log in. An example of this is
+:ref:`rest_single_bug`. However, authenticating yourself allows you to see
+non-public information, for example, a bug that is not publicly visible.
+
+There are two ways to authenticate yourself:
+
+**API Keys**
+
+You can specify ``Bugzilla_api_key`` or simply ``api_key`` as an argument to
+any call, and you will be logged in as that user if the key is correct and has
+not been revoked. You can set up an API key by using the 'API Key' tab in the
+Preferences pages.
+
+**Login and Password**
+
+You can specify ``Bugzilla_login`` and ``Bugzilla_password`` or simply
+``login`` and ``password`` respectively, as arguments to any call, and you will
+be logged in as that user if your credentials are correct.
+
+======================  =======  ==============================================
+name                    type     description
+======================  =======  ==============================================
+**Bugzilla_login**      string   A user's login name.
+**Bugzilla_password**   string   That user's password.
+Bugzilla_restrictlogin  boolean  If true, then your login will only be
+                                 valid for your IP address.
+======================  =======  ==============================================
+
+The ``Bugzilla_restrictlogin`` option is only used when you have also
+specified ``Bugzilla_login`` and ``Bugzilla_password``.
+
+There is also a deprecated method of authentication described below that will be
+removed in the version after Bugzilla 5.0.
+
+**Bugzilla Tokens**
+
+You can use :ref:`rest_user_login` to log in as a Bugzilla user. This issues a
+token that you must then use in future calls. Just use the value for ``token``
+and pass as either ``Bugzilla_token`` or simply ``token`` as arguments to an
+API call.
+
+==================  ======  ===================================================
+name                type    description
+==================  ======  ===================================================
+**Bugzilla_token**  string  You can specify this as argument to any call,
+                            and you will be logged in as that user if the
+                            token is correct. This is the token returned
+                            when calling :ref:`rest_user_login` mentioned
+                            above.
+==================  ======  ===================================================
+
+An error is thrown if you pass an invalid token; you will need to log in again
+to get a new token.
+
+Also starting with Bugzilla 5.0, login cookies are no longer returned by
+:ref:`rest_user_login` due to security concerns.
+
+Useful Parameters
+-----------------
+
+Many calls take common arguments. These are documented below and linked from
+the individual calls where these parameters are used.
+
+**Including Fields**
+
+Many calls return an array of objects with various fields in the objects. (For
+example, :ref:`rest_single_bug` returns a list of ``bugs`` that have fields like
+``id``, ``summary``,  ``creation_time``, etc.)
+
+These parameters allow you to limit what fields are present in the objects, to
+improve performance or save some bandwidth.
+
+``include_fields``: The (case-sensitive) names of fields in the response data.
+Only the fields specified in the object will be returned, the rest will not be
+included. Fields should be comma delimited.
+
+Invalid field names are ignored.
+
+Example request to :ref:`rest_user_get`:
+
+.. code-block:: text
+
+   GET /rest/user/1?include_fields=id,name
+
+would return something like:
+
+.. code-block:: js
+
+   {
+     "users" : [
+       {
+         "id" : 1,
+         "name" : "user@domain.com"
+       }
+     ]
+   }
+
+**Excluding Fields**
+
+``exclude_fields``: The (case-sensitive) names of fields in the return value. The\
+fields specified will not be included in the returned hashes. Fields should
+be comma delimited.
+
+Invalid field names are ignored.
+
+Specifying fields here overrides ``include_fields``, so if you specify a
+field in both, it will be excluded, not included.
+
+Example request to :ref:`rest_user_get`:
+
+.. code-block:: js
+
+   GET /rest/user/1?exclude_fields=name
+
+would return something like:
+
+.. code-block:: js
+
+   {
+     "users" : [
+       {
+         "id" : 1,
+         "real_name" : "John Smith"
+       }
+     ]
+   }
+
+Some calls support specifying "subfields". If a call states that it supports
+"subfield" restrictions, you can restrict what information is returned within
+the first field. For example, if you call :ref:`rest_product_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
+subfield.
+
+There are several shortcut identifiers to ask for only certain groups of
+fields to be returned or excluded:
+
+=========  =====================================================================
+value      description
+=========  =====================================================================
+_all       All possible fields are returned if this is specified in
+           ``include_fields``.
+_default   Default fields are returned if ``include_fields`` is empty or
+           this is specified. This is useful if you want the default
+           fields in addition to a field that is not normally returned.
+_extra     Extra fields are not returned by default and need to be manually
+           specified in ``include_fields`` either by exact field name, or adding
+           ``_extra``.
+ _custom   Custom fields are normally returned by default unless this is added
+           to ``exclude_fields``. Also you can use it in ``include_fields`` if
+           for example you want specific field names plus all custom fields.
+           Custom fields are normally only relevant to bug objects.
+=========  =====================================================================

docs/en/rst/api/core/v1/index.rst

+Core API v1
+===========
+
+.. toctree::
+
+   general
+   attachment
+   bug
+   bug-user-last-visit
+   bugzilla
+   classification
+   comment
+   component
+   field
+   flagtype
+   group
+   product
+   user

docs/en/rst/extensions.rst

@@ -5,7 +5,6 @@ Your Bugzilla installation has the following extensions available (as of the
 last time you compiled the documentation):
 
 .. toctree::
-   :maxdepth: 1
    :glob:
    
-   extensions/*
+   extensions/*/*

docs/en/rst/index.rst

@@ -16,6 +16,7 @@ Bugzilla Documentation
    security
    using
    extensions
+   api
    customization
    patches
    troubleshooting

docs/en/rst/installation.rst

@@ -748,8 +748,8 @@ Without this directive, Apache will not follow symbolic links
 to places outside its own directory structure, and you will be
 unable to run Bugzilla.
 
-Apache *httpd * log files with bugzilla
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Apache *httpd* log files with bugzilla
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 For security reasons it is recommended to prevent Apache from logging
 query strings.
@@ -761,8 +761,8 @@ reasons we recommend configuring Apache to not include the query-string in its l
 files to avoid storing passwords in clear text on the server.
 
 #. Load :file:`httpd.conf` or :file:`apache2.conf` in your editor.
-	 In most of the Linux distributions this file is found in :folder:`/etc/httpd/conf/httpd.conf`
-	 or in :folder:`/etc/apache2/apache2.conf`.
+   In most of the Linux distributions this file is found in :folder:`/etc/httpd/conf/httpd.conf`
+   or in :folder:`/etc/apache2/apache2.conf`.
 
 #. Find the following line in the above mentioned file.
    LogFormat "%v:%p %h %l %u %t \"%r\" %>s %O \"%{Referer}i\" \"%{User-Agent}i\"" vhost_combined.

docs/makedocs.pl

@@ -26,7 +26,8 @@ use strict;
 
 use Cwd;
 use File::Find;
-use File::Copy;
+use File::Basename;
+use File::Copy::Recursive qw(rcopy);
 
 # We need to be in this directory to use our libraries.
 BEGIN {
@@ -48,7 +49,8 @@ if (eval { require Pod::Simple }) {
     $pod_simple = 1;
 };
 
-use Bugzilla::Constants qw(BUGZILLA_VERSION);
+use Bugzilla;
+use Bugzilla::Constants qw(BUGZILLA_VERSION bz_locations);
 
 use File::Path qw(rmtree);
 use File::Which qw(which);
@@ -126,23 +128,43 @@ foreach my $lang (@langs) {
 
     next if grep { $_ eq '--pod-only' } @ARGV;
 
-    # Collect up local extension documentation into the extensions/ dir.
-    sub wanted {
-        if ($File::Find::dir =~ /\/doc\/?$/ &&
-            $_ =~ /\.rst$/)
-        {
-            copy($File::Find::name, "rst/extensions");
+    chdir $docparent;
+
+    # Generate extension documentation, both normal and API
+    my $ext_dir = bz_locations()->{'extensionsdir'};
+    my @ext_paths = grep { $_ !~ /\/create\.pl$/ && ! -e "$_/disabled" }
+                    glob("$ext_dir/*");
+    my %extensions;
+    foreach my $item (@ext_paths) {
+        my $basename = basename($item);
+        if (-d "$item/docs/$lang/rst") {
+            $extensions{$basename} = "$item/docs/$lang/rst";
         }
-    };
+    }
 
+    # Collect up local extension documentation into the extensions/ dir.
     # Clear out old extensions docs
     rmtree('rst/extensions', 0, 1);
     mkdir('rst/extensions');
-    
-    find({
-        'wanted' => \&wanted,
-        'no_chdir' => 1,
-    }, "$docparent/../extensions");
+    rmtree('rst/api/extensions', 0, 1);
+    mkdir('rst/api/extensions');
+
+    foreach my $ext_name (keys %extensions) {
+        foreach my $path (glob($extensions{$ext_name} . "/*")) {
+            my ($file, $dir) = fileparse($path);
+            if ($file eq 'api') {
+                my $dst = "$docparent/$lang/rst/api/extensions/$ext_name";
+                mkdir($dst) unless -d $dst;
+                rcopy("$path/*", $dst);
+                next;
+            }
+            my $dst = "$docparent/$lang/rst/extensions/$ext_name";
+            mkdir($dst) unless -d $dst;
+            rcopy($path, "$dst/$file");
+        }
+    }
+
+    chdir "$docparent/$lang";
 
     MakeDocs('HTML', 'make html');
     MakeDocs('TXT', 'make text');

extensions/Example/docs/en/rst/api/v1/index.rst

+Example API v1
+==============
+
+Here is where you place your API docs for the Example extension.

extensions/Example/doc/example.rst → extensions/Example/docs/en/rst/example.rst

@@ -19,4 +19,3 @@ documentation is copied into the same directory. So, for example, this file
 is called :file:`example.rst`, as it's part of the Example extension. If you
 need multiple documentation files, prefix the filename with the name of your
 extension, e.g. :file:`example-extra.rst`.
-