module => 'Text::Markdown',
version => '1.0.26',
feature => ['markdown'],
+ },
+
+ # Documentation
+ {
+ package => 'File-Copy-Recursive',
+ module => 'File::Copy::Recursive',
+ version => 0,
+ feature => ['documentation'],
}
);
--- /dev/null
+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*
--- /dev/null
+Attachments
+===========
+
+The Bugzilla API for creating, changing, and getting the details of attachments.
+
+.. _rest_attachments:
+
+Get Attachment
+--------------
+
+This allows you to get data about attachments, given a list of bugs and/or
+attachment IDs. Private attachments will only be returned if you are in the
+appropriate group or if you are the submitter of the attachment.
+
+**Request**
+
+To get all current attachments for a bug:
+
+.. code-block:: text
+
+ GET /rest/bug/(bug_id)/attachment
+
+To get a specific attachment based on attachment ID:
+
+.. code-block:: text
+
+ GET /rest/bug/attachment/(attachment_id)
+
+One of the below must be specified.
+
+================= ==== ======================================================
+name type description
+================= ==== ======================================================
+**bug_id** int Integer bug ID.
+**attachment_id** int Integer attachment ID.
+================= ==== ======================================================
+
+**Response**
+
+.. code-block:: js
+
+ {
+ "bugs" : {
+ "1345" : [
+ { (attachment) },
+ { (attachment) }
+ ],
+ "9874" : [
+ { (attachment) },
+ { (attachment) }
+ ],
+ },
+ "attachments" : {
+ "234" : { (attachment) },
+ "123" : { (attachment) },
+ }
+ }
+
+An object containing two elements: ``bugs`` and ``attachments``.
+
+The attachments for the bug that you specified in the ``bug_id`` argument in
+input are returned in ``bugs`` on output. ``bugs`` is a object that has integer
+bug IDs for keys and the values are arrays of objects as attachments.
+(Fields for attachments are described below.)
+
+For the attachment that you specified directly in ``attachment_id``, they
+are returned in ``attachments`` on output. This is a object where the attachment
+ids point directly to objects describing the individual attachment.
+
+The fields for each attachment (where it says ``(attachment)`` in the
+sample response above) are:
+
+================ ======== =====================================================
+name type description
+================ ======== =====================================================
+data base64 The raw data of the attachment, encoded as Base64.
+size int The length (in bytes) of the attachment.
+creation_time datetime The time the attachment was created.
+last_change_time datetime The last time the attachment was modified.
+id int The numeric ID of the attachment.
+bug_id int The numeric ID of the bug that the attachment is
+ attached to.
+file_name string The file name of the attachment.
+summary string A short string describing the attachment.
+content_type string The MIME type of the attachment.
+is_private boolean ``true`` if the attachment is private (only visible
+ to a certain group called the "insidergroup",
+ ``false`` otherwise.
+is_obsolete boolean ``true`` if the attachment is obsolete, ``false``
+ otherwise.
+is_patch boolean ``true`` if the attachment is a patch, ``false``
+ otherwise.
+creator string The login name of the user that created the
+ attachment.
+flags array Array of objects, each containing the information
+ about the flag currently set for each attachment.
+ Each flag object contains items descibed in the
+ Flag object below.
+================ ======== =====================================================
+
+Flag object:
+
+================= ======== ====================================================
+name type description
+================= ======== ====================================================
+id int The ID of the flag.
+name string The name of the flag.
+type_id int The type ID of the flag.
+creation_date datetime The timestamp when this flag was originally created.
+modification_date datetime The timestamp when the flag was last modified.
+status string The current status of the flag such as ?, +, or -.
+setter string The login name of the user who created or last
+ modified the flag.
+requestee string The login name of the user this flag has been
+ requested to be granted or denied. Note, this field
+ is only returned if a requestee is set.
+================= ======== ====================================================
+
+.. _rest_add_attachment:
+
+Create Attachment
+-----------------
+
+This allows you to add an attachment to a bug in Bugzilla.
+
+**Request**
+
+To create attachment on a current bug:
+
+.. code-block:: text
+
+ POST /rest/bug/(bug_id)/attachment
+
+.. code-block:: js
+
+ {
+ "ids" : [ 35 ],
+ "is_patch" : true,
+ "comment" : "This is a new attachment comment",
+ "is_markdown" : true,
+ "summary" : "Test Attachment",
+ "content_type" : "text/plain",
+ "data" : "(Some patch content)",
+ "file_name" : "test_attachment.patch",
+ "obsoletes" : [],
+ "is_private" : false,
+ "flags" : [
+ {
+ "name" : "review",
+ "status" : "?",
+ "requestee" : "user@bugzilla.org",
+ "new" : true
+ }
+ ]
+ }
+
+
+The params to include in the POST body, as well as the returned
+data format, are the same as below. The ``bug_id`` param will be
+overridden as it it pulled from the URL path.
+
+================ ======= ======================================================
+name type description
+================ ======= ======================================================
+**ids** array The IDs or aliases of bugs that you want to add this
+ attachment to. The same attachment and comment will be
+ added to all these bugs.
+**data** string The content of the attachment. If the content of the
+ attachment is not ASCII text such as
+ ``application/octet-stream`` you must encode it in
+ base64 using an appropriate client library such as
+ ``MIME::Base64`` for Perl.
+**file_name** string The "file name" that will be displayed in the UI for
+ this attachment and also downloaded copies will be
+ given.
+**summary** string A short string describing the attachment.
+**content_type** string The MIME type of the attachment, like ``text/plain``
+ or ``image/png``.
+comment string A comment to add along with this attachment.
+is_patch boolean ``true`` if Bugzilla should treat this attachment as a
+ patch. If you specify this, you do not need to specify
+ a ``content_type``. The ``content_type`` of the
+ attachment will be forced to ``text/plain``. Defaults
+ to ``false`` if not specified.
+is_private boolean ``true`` if the attachment should be private
+ (restricted to the "insidergroup"), ``false`` if the
+ attachment should be public. Defaults to ``false`` if
+ not specified.
+is_markdown boolean If set to ``true``, the comment has Markdown structures;
+ otherwise, it is normal text.
+flags array Flags objects to add to the attachment. The object
+ format is described in the Flag object below.
+================ ======= ======================================================
+
+Flag object:
+
+To create a flag, at least the ``status`` and the ``type_id`` or ``name`` must
+be provided. An optional requestee can be passed if the flag type is requestable
+to a specific user.
+
+========= ====== ==============================================================
+name type description
+========= ====== ==============================================================
+name string The name of the flag type.
+type_id int The internal flag type ID.
+status string The flags new status (i.e. "?", "+", "-" or "X" to clear a
+ flag).
+requestee string The login of the requestee if the flag type is requestable to
+ a specific user.
+========= ====== ==============================================================
+
+**Response**
+
+.. code-block:: js
+
+ {
+ "ids" : [
+ "2797"
+ ]
+ }
+
+==== ===== =========================
+name type description
+==== ===== =========================
+ids array Attachment IDs created.
+==== ===== =========================
+
+.. _rest_update_attachment:
+
+Update Attachment
+-----------------
+
+This allows you to update attachment metadata in Bugzilla.
+
+**Request**
+
+To update attachment metadata on a current attachment:
+
+.. code-block:: text
+
+ PUT /rest/bug/attachment/(attachment_id)
+
+.. code-block:: js
+
+ {
+ "ids" : [ 2796 ],
+ "summary" : "Test XML file",
+ "comment" : "Changed this from a patch to a XML file",
+ "is_markdown" : true,
+ "content_type" : "text/xml",
+ "is_patch" : 0
+ }
+
+================= ===== =======================================================
+name type description
+================= ===== =======================================================
+**attachment_id** int Integer attachment ID.
+**ids** array The IDs of the attachments you want to update.
+================= ===== =======================================================
+
+============ ======= ==========================================================
+name type description
+============ ======= ==========================================================
+file_name string The "file name" that will be displayed in the UI for this
+ attachment.
+summary string A short string describing the attachment.
+comment string An optional comment to add to the attachment's bug.
+is_markdown boolean If set to ``true``, the comment has Markdown structures;
+ otherwise, it is normal text.
+content_type string The MIME type of the attachment, like ``text/plain``
+ or ``image/png``.
+is_patch boolean ``true`` if Bugzilla should treat this attachment as a
+ patch. If you specify this, you do not need to specify a
+ ``content_type``. The ``content_type`` of the attachment
+ will be forced to ``text/plain``.
+is_private boolean ``true`` if the attachment should be private (restricted
+ to the "insidergroup"), ``false`` if the attachment
+ should be public.
+is_obsolete boolean ``true`` if the attachment is obsolete, ``false``
+ otherwise.
+flags array An array of Flag objects with changes to the flags. The
+ object format is described in the Flag object below.
+============ ======= ==========================================================
+
+Flag object:
+
+The following values can be specified. At least the ``status`` and one of
+``type_id``, ``id``, or ``name`` must be specified. If a type_id or name matches
+a single currently set flag, the flag will be updated unless ``new`` is specified.
+
+========= ======= =============================================================
+name type description
+========= ======= =============================================================
+name string The name of the flag that will be created or updated.
+type_id int The internal flag type ID that will be created or updated.
+ You will need to specify the ``type_id`` if more than one
+ flag type of the same name exists.
+status string The flags new status (i.e. "?", "+", "-" or "X" to clear a
+ flag).
+requestee string The login of the requestee if the flag type is requestable
+ to a specific user.
+id int Use ID to specify the flag to be updated. You will need to
+ specify the ``id`` if more than one flag is set of the same
+ name.
+new boolean Set to true if you specifically want a new flag to be
+ created.
+========= ======= =============================================================
+
+**Response**
+
+.. code-block:: js
+
+ {
+ "attachments" : [
+ {
+ "changes" : {
+ "content_type" : {
+ "added" : "text/xml",
+ "removed" : "text/plain"
+ },
+ "is_patch" : {
+ "added" : "0",
+ "removed" : "1"
+ },
+ "summary" : {
+ "added" : "Test XML file",
+ "removed" : "test patch"
+ }
+ },
+ "id" : 2796,
+ "last_change_time" : "2014-09-29T14:41:53Z"
+ }
+ ]
+ }
+
+``attachments`` (array) Change objects with the following items:
+
+================ ======== =====================================================
+name type description
+================ ======== =====================================================
+id int The ID of the attachment that was updated.
+last_change_time datetime The exact time that this update was done at, for this
+ attachment. If no update was done (that is, no fields
+ had their values changed and no comment was added)
+ then this will instead be the last time the
+ attachment was updated.
+changes object The changes that were actually done on this
+ attachment. The keys are the names of the fields that
+ were changed, and the values are an object with two
+ items:
+
+ * added: (string) The values that were added to this
+ field. Possibly a comma-and-space-separated list
+ if multiple values were added.
+ * removed: (string) The values that were removed from
+ this field.
+================ ======== =====================================================
--- /dev/null
+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.
+============= ======== ============================================
--- /dev/null
+Bugs
+====
+
+The REST API for creating, changing, and getting the details of bugs.
+
+This part of the Bugzilla REST API allows you to file new bugs in Bugzilla and
+to get information about existing bugs.
+
+.. _rest_single_bug:
+
+Get Bug
+-------
+
+Gets information about particular bugs in the database.
+
+**Request**
+
+To get information about a particular bug using its ID or alias:
+
+.. code-block:: text
+
+ GET /rest/bug/(id_or_alias)
+
+You can also use :ref:`rest_search_bugs` to return more than one bug at a time
+by specifying bug IDs as the search terms.
+
+.. code-block:: text
+
+ GET /rest/bug?id=12434,43421
+
+================ ===== ======================================================
+name type description
+================ ===== ======================================================
+**id_or_alias** mixed An integer bug ID or a bug alias string.
+================ ===== ======================================================
+
+**Response**
+
+.. code-block:: js
+
+ {
+ "faults": [],
+ "bugs": [
+ {
+ "assigned_to_detail": {
+ "id": 2,
+ "real_name": "Test User",
+ "name": "user@bugzilla.org",
+ "email": "user@bugzilla.org"
+ },
+ "flags": [
+ {
+ "type_id": 11,
+ "modification_date": "2014-09-28T21:03:47Z",
+ "name": "blocker",
+ "status": "?",
+ "id": 2906,
+ "setter": "user@bugzilla.org",
+ "creation_date": "2014-09-28T21:03:47Z"
+ }
+ ],
+ "resolution": "INVALID",
+ "id": 35,
+ "qa_contact": "",
+ "version": "1.0",
+ "status": "RESOLVED",
+ "creator": "user@bugzilla.org",
+ "cf_drop_down": "---",
+ "summary": "test bug",
+ "last_change_time": "2014-09-23T19:12:17Z",
+ "platform": "All",
+ "url": "",
+ "classification": "Unclassified",
+ "cc_detail": [
+ {
+ "id": 786,
+ "real_name": "Foo Bar",
+ "name": "foo@bar.com",
+ "email": "foo@bar.com"
+ },
+ ],
+ "priority": "P1",
+ "is_confirmed": true,
+ "creation_time": "2000-07-25T13:50:04Z",
+ "assigned_to": "user@bugzilla.org",
+ "flags": [],
+ "alias": [],
+ "cf_large_text": "",
+ "groups": [],
+ "op_sys": "All",
+ "cf_bug_id": null,
+ "depends_on": [],
+ "is_cc_accessible": true,
+ "is_open": false,
+ "cf_qa_list_4": "---",
+ "keywords": [],
+ "cc": [
+ "foo@bar.com",
+ ],
+ "see_also": [],
+ "deadline": null,
+ "is_creator_accessible": true,
+ "whiteboard": "",
+ "dupe_of": null,
+ "target_milestone": "---",
+ "cf_mulitple_select": [],
+ "component": "SaltSprinkler",
+ "severity": "critical",
+ "cf_date": null,
+ "product": "FoodReplicator",
+ "creator_detail": {
+ "id": 28,
+ "real_name": "hello",
+ "name": "user@bugzilla.org",
+ "email": "namachi@netscape.com"
+ },
+ "cf_free_text": "",
+ "blocks": []
+ }
+ ]
+ }
+
+``bugs`` (array) Each bug object contains information about the bugs with valid
+ids containing the following items:
+
+These fields are returned by default or by specifying ``_default`` in
+``include_fields``.
+
+===================== ======== ================================================
+name type description
+===================== ======== ================================================
+actual_time double The total number of hours that this bug has
+ taken so far. If you are not in the time-tracking
+ group, this field will not be included in the
+ return value.
+alias array The unique aliases of this bug. An empty array
+ will be returned if this bug has no aliases.
+assigned_to string The login name of the user to whom the bug is
+ assigned.
+assigned_to_detail object An object containing detailed user information
+ for the assigned_to. To see the keys included
+ in the user detail object, see below.
+blocks array The IDs of bugs that are "blocked" by this bug.
+cc array The login names of users on the CC list of this
+ bug.
+cc_detail array Array of objects containing detailed user
+ information for each of the cc list members.
+ To see the keys included in the user detail
+ object, see below.
+classification string The name of the current classification the bug
+ is in.
+component string The name of the current component of this bug.
+creation_time datetime When the bug was created.
+creator string The login name of the person who filed this bug
+ (the reporter).
+creator_detail object An object containing detailed user information
+ for the creator. To see the keys included in the
+ user detail object, see below.
+deadline string The day that this bug is due to be completed, in
+ the format ``YYYY-MM-DD``.
+depends_on array The IDs of bugs that this bug "depends on".
+dupe_of int The bug ID of the bug that this bug is a
+ duplicate of. If this bug isn't a duplicate of
+ any bug, this will be null.
+estimated_time double The number of hours that it was estimated that
+ this bug would take. If you are not in the
+ time-tracking group, this field will not be
+ included in the return value.
+flags array An array of objects containing the information
+ about flags currently set for the bug. Each flag
+ objects contains the following items
+groups array The names of all the groups that this bug is in.
+id int The unique numeric ID of this bug.
+is_cc_accessible boolean If true, this bug can be accessed by members of
+ the CC list, even if they are not in the groups
+ the bug is restricted to.
+is_confirmed boolean ``true`` if the bug has been confirmed. Usually
+ this means that the bug has at some point been
+ moved out of the ``UNCONFIRMED`` status and into
+ another open status.
+is_open boolean ``true`` if this bug is open, ``false`` if it
+ is closed.
+is_creator_accessible boolean If ``true``, this bug can be accessed by the
+ creator of the bug, even if they are not a
+ member of the groups the bug is restricted to.
+keywords array Each keyword that is on this bug.
+last_change_time datetime When the bug was last changed.
+op_sys string The name of the operating system that the bug
+ was filed against.
+platform string The name of the platform (hardware) that the bug
+ was filed against.
+priority string The priority of the bug.
+product string The name of the product this bug is in.
+qa_contact string The login name of the current QA Contact on the
+ bug.
+qa_contact_detail object An object containing detailed user information
+ for the qa_contact. To see the keys included in
+ the user detail object, see below.
+remaining_time double The number of hours of work remaining until work
+ on this bug is complete. If you are not in the
+ time-tracking group, this field will not be
+ included in the return value.
+resolution string The current resolution of the bug, or an empty
+ string if the bug is open.
+see_also array The URLs in the See Also field on the bug.
+severity string The current severity of the bug.
+status string The current status of the bug.
+summary string The summary of this bug.
+target_milestone string The milestone that this bug is supposed to be
+ fixed by, or for closed bugs, the milestone that
+ it was fixed for.
+update_token string The token that you would have to pass to the
+ ``process_bug.cgi`` page in order to update this
+ bug. This changes every time the bug is updated.
+ This field is not returned to logged-out users.
+url string A URL that demonstrates the problem described in
+ the bug, or is somehow related to the bug report.
+version string The version the bug was reported against.
+whiteboard string The value of the "status whiteboard" field on
+ the bug.
+===================== ======== ================================================
+
+Custom fields:
+
+Every custom field in this installation will also be included in the
+return value. Most fields are returned as strings. However, some field types have
+different return values.
+
+Normally custom fields are returned by default similar to normal bug fields or
+you can specify only custom fields by using ``_custom`` in ``include_fields``.
+
+Extra fields:
+
+These fields are returned only by specifying ``_extra`` or the field name in
+``include_fields``.
+
+==== ===== ====================================================================
+name type description
+==== ===== ====================================================================
+tags array Each array item is a tag name. Note that tags are
+ personal to the currently logged in user and are not the same as
+ comment tags.
+==== ===== ====================================================================
+
+User object:
+
+========= ====== ==============================================================
+name type description
+========= ====== ==============================================================
+id int The user ID for this user.
+real_name string The 'real' name for this user, if any.
+name string The user's Bugzilla login.
+email string The user's email address. Currently this is the same value as
+ the name.
+========= ====== ==============================================================
+
+Flag object:
+
+================= ======== ====================================================
+name type description
+================= ======== ====================================================
+id int The ID of the flag.
+name string The name of the flag.
+type_id int The type ID of the flag.
+creation_date datetime The timestamp when this flag was originally created.
+modification_date datetime The timestamp when the flag was last modified.
+status string The current status of the flag.
+setter string The login name of the user who created or last
+ modified the flag.
+requestee string The login name of the user this flag has been
+ requested to be granted or denied. Note, this field
+ is only returned if a requestee is set.
+================= ======== ====================================================
+
+Custom field object:
+
+You can specify to only return custom fields by specifying ``_custom`` or the
+field name in ``include_fields``.
+
+* Bug ID Fields: (int)
+* Multiple-Selection Fields: (array of strings)
+* Date/Time Fields: (datetime)
+
+.. _rest_history:
+
+Bug History
+-----------
+
+Gets the history of changes for particular bugs in the database.
+
+**Request**
+
+To get the history for a specific bug ID:
+
+.. code-block:: text
+
+ GET /rest/bug/(id)/history
+
+To get the history for a bug since a specific date:
+
+.. code-block:: text
+
+ GET /rest/bug/(id)/history?new_since=YYYY-MM-DD
+
+========= ======== ============================================================
+name type description
+========= ======== ============================================================
+**id** mixed An integer bug ID or alias.
+new_since datetime A datetime timestamp to only show history since.
+========= ======== ============================================================
+
+**Response**
+
+.. code-block:: js
+
+ {
+ "bugs": [
+ {
+ "alias": [],
+ "history": [
+ {
+ "when": "2014-09-23T19:12:17Z",
+ "who": "user@bugzilla.org",
+ "changes": [
+ {
+ "added": "P1",
+ "field_name": "priority",
+ "removed": "P2"
+ },
+ {
+ "removed": "blocker",
+ "field_name": "severity",
+ "added": "critical"
+ }
+ ]
+ },
+ {
+ "when": "2014-09-28T21:03:47Z",
+ "who": "user@bugzilla.org",
+ "changes": [
+ {
+ "added": "blocker?",
+ "removed": "",
+ "field_name": "flagtypes.name"
+ }
+ ]
+ }
+ ],
+ "id": 35
+ }
+ ]
+ }
+
+``bugs`` (array) Bug objects each containing the following items:
+
+======= ===== =================================================================
+name type description
+======= ===== =================================================================
+id int The numeric ID of the bug.
+alias array The unique aliases of this bug. An empty array will be returned
+ if this bug has no aliases.
+history array An array of History objects.
+======= ===== =================================================================
+
+History object:
+
+======= ======== ==============================================================
+name type description
+======= ======== ==============================================================
+when datetime The date the bug activity/change happened.
+who string The login name of the user who performed the bug change.
+changes array An array of Change objects which contain all the changes that
+ happened to the bug at this time (as specified by ``when``).
+======= ======== ==============================================================
+
+Change object:
+
+============= ====== ==========================================================
+name type description
+============= ====== ==========================================================
+field_name string The name of the bug field that has changed.
+removed string The previous value of the bug field which has been
+ deleted by the change.
+added string The new value of the bug field which has been added
+ by the change.
+attachment_id int The ID of the attachment that was changed.
+ This only appears if the change was to an attachment,
+ otherwise ``attachment_id`` will not be present in this
+ object.
+============= ====== ==========================================================
+
+.. _rest_search_bugs:
+
+Search Bugs
+-----------
+
+Allows you to search for bugs based on particular criteria.
+
+**Request**
+
+To search for bugs:
+
+.. code-block:: text
+
+ GET /rest/bug
+
+Unless otherwise specified in the description of a parameter, bugs are
+returned if they match *exactly* the criteria you specify in these
+parameters. That is, we don't match against substrings--if a bug is in
+the "Widgets" product and you ask for bugs in the "Widg" product, you
+won't get anything.
+
+Criteria are joined in a logical AND. That is, you will be returned
+bugs that match *all* of the criteria, not bugs that match *any* of
+the criteria.
+
+Each parameter can be either the type it says, or a list of the types
+it says. If you pass an array, it means "Give me bugs with *any* of
+these values." For example, if you wanted bugs that were in either
+the "Foo" or "Bar" products, you'd pass:
+
+.. code-block:: text
+
+ GET /rest/bug?product=Foo&product=Bar
+
+Some Bugzillas may treat your arguments case-sensitively, depending
+on what database system they are using. Most commonly, though, Bugzilla is
+not case-sensitive with the arguments passed (because MySQL is the
+most-common database to use with Bugzilla, and MySQL is not case sensitive).
+
+In addition to the fields listed below, you may also use criteria that
+is similar to what is used in the Advanced Search screen of the Bugzilla
+UI. This includes fields specified by ``Search by Change History`` and
+``Custom Search``. The easiest way to determine what the field names are and what
+format Bugzilla expects is to first construct your query using the
+Advanced Search UI, execute it and use the query parameters in they URL
+as your query for the REST call.
+
+================ ======== =====================================================
+name type description
+================ ======== =====================================================
+alias array The unique aliases of this bug. An empty array will
+ be returned if this bug has no aliases.
+assigned_to string The login name of a user that a bug is assigned to.
+component string The name of the Component that the bug is in. Note
+ that if there are multiple Components with the same
+ name, and you search for that name, bugs in *all*
+ those Components will be returned. If you don't want
+ this, be sure to also specify the ``product`` argument.
+creation_time datetime Searches for bugs that were created at this time or
+ later. May not be an array.
+creator string The login name of the user who created the bug. You
+ can also pass this argument with the name
+ ``reporter``, for backwards compatibility with
+ older Bugzillas.
+id int The numeric ID of the bug.
+last_change_time datetime Searches for bugs that were modified at this time
+ or later. May not be an array.
+limit int Limit the number of results returned. If the limit
+ is more than zero and higher than the maximum limit
+ set by the administrator, then the maximum limit will
+ be used instead. If you set the limit equal to zero,
+ then all matching results will be returned instead.
+offset int Used in conjunction with the ``limit`` argument,
+ ``offset`` defines the starting position for the
+ search. For example, given a search that would
+ return 100 bugs, setting ``limit`` to 10 and
+ ``offset`` to 10 would return bugs 11 through 20
+ from the set of 100.
+op_sys string The "Operating System" field of a bug.
+platform string The Platform (sometimes called "Hardware") field of
+ a bug.
+priority string The Priority field on a bug.
+product string The name of the Product that the bug is in.
+resolution string The current resolution--only set if a bug is closed.
+ You can find open bugs by searching for bugs with an
+ empty resolution.
+severity string The Severity field on a bug.
+status string The current status of a bug (not including its
+ resolution, if it has one, which is a separate field
+ above).
+summary string Searches for substrings in the single-line Summary
+ field on bugs. If you specify an array, then bugs
+ whose summaries match *any* of the passed substrings
+ will be returned. Note that unlike searching in the
+ Bugzilla UI, substrings are not split on spaces. So
+ searching for ``foo bar`` will match "This is a foo
+ bar" but not "This foo is a bar". ``['foo', 'bar']``,
+ would, however, match the second item.
+tags string Searches for a bug with the specified tag. If you
+ specify an array, then any bugs that match *any* of
+ the tags will be returned. Note that tags are
+ personal to the currently logged in user.
+target_milestone string The Target Milestone field of a bug. Note that even
+ if this Bugzilla does not have the Target Milestone
+ field enabled, you can still search for bugs by
+ Target Milestone. However, it is likely that in that
+ case, most bugs will not have a Target Milestone set
+ (it defaults to "---" when the field isn't enabled).
+qa_contact string The login name of the bug's QA Contact. Note that
+ even if this Bugzilla does not have the QA Contact
+ field enabled, you can still search for bugs by QA
+ Contact (though it is likely that no bug will have a
+ QA Contact set, if the field is disabled).
+url string The "URL" field of a bug.
+version string The Version field of a bug.
+whiteboard string Search the "Status Whiteboard" field on bugs for a
+ substring. Works the same as the ``summary`` field
+ described above, but searches the Status Whiteboard
+ field.
+quicksearch string Search for bugs using quicksearch syntax.
+================ ======== =====================================================
+
+**Response**
+
+The same as :ref:`rest_single_bug`.
+
+.. _rest_create_bug:
+
+Create Bug
+----------
+
+This allows you to create a new bug in Bugzilla. If you specify any
+invalid fields, an error will be thrown stating which field is invalid.
+If you specify any fields you are not allowed to set, they will just be
+set to their defaults or ignored.
+
+You cannot currently set all the items here that you can set on enter_bug.cgi.
+
+The WebService interface may allow you to set things other than those listed
+here, but realize that anything undocumented here may likely change in the
+future.
+
+**Request**
+
+To create a new bug in Bugzilla.
+
+.. code-block:: text
+
+ POST /rest/bug
+
+.. code-block:: js
+
+ {
+ "product" : "TestProduct",
+ "component" : "TestComponent",
+ "version" : "unspecified",
+ "summary" : "'This is a test bug - please disregard",
+ "alias" : "SomeAlias",
+ "op_sys" : "All",
+ "priority" : "P1",
+ "rep_platform" : "All"
+ }
+
+Some params must be set, or an error will be thrown. These params are
+marked in **bold**.
+
+Some parameters can have defaults set in Bugzilla, by the administrator.
+If these parameters have defaults set, you can omit them. These parameters
+are marked (defaulted).
+
+Clients that want to be able to interact uniformly with multiple
+Bugzillas should always set both the params marked required and those
+marked (defaulted), because some Bugzillas may not have defaults set
+for (defaulted) parameters, and then this method will throw an error
+if you don't specify them.
+
+================== ======= ====================================================
+name type description
+================== ======= ====================================================
+**product** string The name of the product the bug is being filed
+ against.
+**component** string The name of a component in the product above.
+**summary** string A brief description of the bug being filed.
+**version** string A version of the product above; the version the
+ bug was found in.
+description string (defaulted) The initial description for this bug.
+ Some Bugzilla installations require this to not be
+ blank.
+op_sys string (defaulted) The operating system the bug was
+ discovered on.
+platform string (defaulted) What type of hardware the bug was
+ experienced on.
+priority string (defaulted) What order the bug will be fixed in by
+ the developer, compared to the developer's other
+ bugs.
+severity string (defaulted) How severe the bug is.
+alias array One or more brief aliases for the bug that can be
+ used instead of a bug number when accessing this bug.
+ Must be unique in all of this Bugzilla.
+assigned_to string A user to assign this bug to, if you don't want it
+ to be assigned to the component owner.
+cc array An array of usernames to CC on this bug.
+comment_is_private boolean If set to ``true``, the description is private,
+ otherwise it is assumed to be public.
+is_markdown boolean If set to ``true``, the description has Markdown
+ structures; otherwise it is normal text.
+groups array An array of group names to put this bug into. You
+ can see valid group names on the Permissions tab of
+ the Preferences screen, or, if you are an
+ administrator, in the Groups control panel. If you
+ don't specify this argument, then the bug will be
+ added into all the groups that are set as being
+ "Default" for this product. (If you want to avoid
+ that, you should specify ``groups`` as an empty
+ array.)
+qa_contact string If this installation has QA Contacts enabled, you
+ can set the QA Contact here if you don't want to
+ use the component's default QA Contact.
+status string The status that this bug should start out as. Note
+ that only certain statuses can be set on bug
+ creation.
+resolution string If you are filing a closed bug, then you will have
+ to specify a resolution. You cannot currently
+ specify a resolution of ``DUPLICATE`` for new
+ bugs, though. That must be done with
+ :ref:`rest_update_bug`.
+target_milestone string A valid target milestone for this product.
+flags array Flags objects to add to the bug. The object format
+ is described in the Flag object below.
+================== ======= ====================================================
+
+Flag object:
+
+To create a flag, at least the ``status`` and the ``type_id`` or ``name`` must
+be provided. An optional requestee can be passed if the flag type is requestable
+to a specific user.
+
+========= ====== ==============================================================
+name type description
+========= ====== ==============================================================
+name string The name of the flag type.
+type_id int The internal flag type ID.
+status string The flags new status (i.e. "?", "+", "-" or "X" to clear flag).
+requestee string The login of the requestee if the flag type is requestable
+ to a specific user.
+========= ====== ==============================================================
+
+In addition to the above parameters, if your installation has any custom
+fields, you can set them just by passing in the name of the field and
+its value as a string.
+
+**Response**
+
+.. code-block:: js
+
+ {
+ "id" : 12345
+ }
+
+==== ==== ======================================
+name type description
+==== ==== ======================================
+id int This is the ID of the newly-filed bug.
+==== ==== ======================================
+
+.. _rest_update_bug:
+
+Update Bug
+----------
+
+Allows you to update the fields of a bug. Automatically sends emails
+out about the changes.
+
+**Request**
+
+To update the fields of a current bug.
+
+.. code-block:: text
+
+ PUT /rest/bug/(id_or_alias)
+
+.. code-block:: js
+
+ {
+ "ids" : [35],
+ "status" : "IN_PROGRESS",
+ "keywords" : {
+ "add" : ["funny", "stupid"]
+ }
+ }
+
+The params to include in the PUT body as well as the returned data format,
+are the same as below. You can specify the ID or alias of the bug to update
+either in the URL path and/or in the ``ids`` param. You can use both and they
+will be combined so you can edit more than one bug at a time.
+
+=============== ===== =========================================================
+name type description
+=============== ===== =========================================================
+**id_or_alias** mixed An integer bug ID or alias.
+**ids** array The IDs or aliases of the bugs that you want to modify.
+=============== ===== =========================================================
+
+All following fields specify the values you want to set on the bugs you are
+updating.
+
+===================== ======= =================================================
+name type description
+===================== ======= =================================================
+alias object These specify the aliases of a bug that can be
+ used instead of a bug number when acessing this
+ bug. To set these, you should pass a hash as the
+ value. The object may contain the following
+ items:
+
+ * ``add`` (array) Aliases to add to this field.
+ * ``remove`` (array) Aliases to remove from this
+ field. If the aliases are not already in the
+ field, they will be ignored.
+ * ``set`` (array) An exact set of aliases to set
+ this field to, overriding the current value.
+ If you specify ``set``, then ``add`` and
+ ``remove`` will be ignored.
+
+ You can only set this if you are modifying a
+ single bug. If there is more than one bug
+ specified in ``ids``, passing in a value for
+ ``alias`` will cause an error to be thrown.
+
+ For backwards compatibility, you can also
+ specify a single string. This will be treated as
+ if you specified the set key above.
+assigned_to string The full login name of the user this bug is
+ assigned to.
+blocks object (Same as ``depends_on`` below)
+depends_on object These specify the bugs that this bug blocks or
+ depends on, respectively. To set these, you
+ should pass an object as the value. The object
+ may contain the following items:
+
+ * ``add`` (array) Bug IDs to add to this field.
+ * ``remove`` (array) Bug IDs to remove from this
+ field. If the bug IDs are not already in the
+ field, they will be ignored.
+ * ``set`` (array of) An exact set of bug IDs to
+ set this field to, overriding the current
+ value. If you specify ``set``, then ``add``
+ and ``remove`` will be ignored.
+cc object The users on the cc list. To modify this field,
+ pass an object, which may have the following
+ items:
+
+ * ``add`` (array) User names to add to the CC
+ list. They must be full user names, and an
+ error will be thrown if you pass in an invalid
+ user name.
+ * ``remove`` (array) User names to remove from
+ the CC list. They must be full user names, and
+ an error will be thrown if you pass in an
+ invalid user name.
+is_cc_accessible boolean Whether or not users in the CC list are allowed
+ to access the bug, even if they aren't in a group
+ that can normally access the bug.
+comment object A comment on the change. The object may contain
+ the following items:
+
+ * ``body`` (string) The actual text of the
+ comment. For compatibility with the parameters
+ to :ref:`rest_add_comment`, you can also call
+ this field ``comment``, if you want.
+ * ``is_private`` (boolean) Whether the comment is
+ private or not. If you try to make a comment
+ private and you don't have the permission to,
+ an error will be thrown.
+ * ``is_markdown`` (boolean) If set to ``true``,
+ the comment has Markdown structures, otherwise
+ it is normal text.
+comment_is_private object This is how you update the privacy of comments
+ that are already on a bug. This is a object,
+ where the keys are the ``int`` ID of comments
+ (not their count on a bug, like #1, #2, #3, but
+ their globally-unique ID, as returned by
+ :ref:`rest_comments` and the value is a
+ ``boolean`` which specifies whether that comment
+ should become private (``true``) or public
+ (``false``).
+
+ The comment IDs must be valid for the bug being
+ updated. Thus, it is not practical to use this
+ while updating multiple bugs at once, as a single
+ comment ID will never be valid on multiple bugs.
+component string The Component the bug is in.
+deadline date The Deadline field is a date specifying when the
+ bug must be completed by, in the format
+ ``YYYY-MM-DD``.
+dupe_of int The bug that this bug is a duplicate of. If you
+ want to mark a bug as a duplicate, the safest
+ thing to do is to set this value and *not* set
+ the ``status`` or ``resolutio`` fields. They will
+ automatically be set by Bugzilla to the
+ appropriate values for duplicate bugs.
+estimated_time double The total estimate of time required to fix the
+ bug, in hours. This is the *total* estimate, not
+ the amount of time remaining to fix it.
+flags array An array of Flag change objects. The items needed
+ are described below.
+groups object The groups a bug is in. To modify this field,
+ pass an object, which may have the following
+ items:
+
+ * ``add`` (array) The names of groups to add.
+ Passing in an invalid group name or a group
+ that you cannot add to this bug will cause an
+ error to be thrown.
+ * ``remove`` (array) The names of groups to
+ remove. Passing in an invalid group name or a
+ group that you cannot remove from this bug
+ will cause an error to be thrown.
+keywords object Keywords on the bug. To modify this field, pass
+ an object, which may have the following items:
+
+ * ``add`` (array) The names of keywords to add
+ to the field on the bug. Passing something that
+ isn't a valid keyword name will cause an error
+ to be thrown.
+ * ``remove`` (array) The names of keywords to
+ remove from the field on the bug. Passing
+ something that isn't a valid keyword name will
+ cause an error to be thrown.
+ * ``set`` (array) An exact set of keywords to set
+ the field to, on the bug. Passing something
+ that isn't a valid keyword name will cause an
+ error to be thrown. Specifying ``set``
+ overrides ``add`` and ``remove``.
+op_sys string The Operating System ("OS") field on the bug.
+platform string The Platform or "Hardware" field on the bug.
+priority string The Priority field on the bug.
+product string The name of the product that the bug is in. If
+ you change this, you will probably also want to
+ change ``target_milestone``, ``version``, and
+ ``component``, since those have different legal
+ values in every product.
+
+ If you cannot change the ``target_milestone``
+ field, it will be reset to the default for the
+ product, when you move a bug to a new product.
+
+ You may also wish to add or remove groups, as
+ which groups are
+ valid on a bug depends on the product. Groups
+ that are not valid in the new product will be
+ automatically removed, and groups which are
+ mandatory in the new product will be automaticaly
+ added, but no other automatic group changes will
+ be done.
+
+ .. note::
+ Users can only move a bug into a product if
+ they would normally have permission to file
+ new bugs in that product.
+qa_contact string The full login name of the bug's QA Contact.
+is_creator_accessible boolean Whether or not the bug's reporter is allowed
+ to access the bug, even if they aren't in a group
+ that can normally access the bug.
+remaining_time double How much work time is remaining to fix the bug,
+ in hours. If you set ``work_time`` but don't
+ explicitly set ``remaining_time``, then the
+ ``work_time`` will be deducted from the bug's
+ ``remaining_time``.
+reset_assigned_to boolean If true, the ``assigned_to`` field will be
+ reset to the default for the component that the
+ bug is in. (If you have set the component at the
+ same time as using this, then the component used
+ will be the new component, not the old one.)
+reset_qa_contact boolean If true, the ``qa_contact`` field will be reset
+ to the default for the component that the bug is
+ in. (If you have set the component at the same
+ time as using this, then the component used will
+ be the new component, not the old one.)
+resolution string The current resolution. May only be set if you
+ are closing a bug or if you are modifying an
+ already-closed bug. Attempting to set the
+ resolution to *any* value (even an empty or null
+ string) on an open bug will cause an error to be
+ thrown.
+
+ .. note::
+ If you change the ``status`` field to an open
+ status, the resolution field will automatically
+ be cleared, so you don't have to clear it
+ manually.
+see_also object The See Also field on a bug, specifying URLs to
+ bugs in other bug trackers. To modify this field,
+ pass an object, which may have the following
+ items:
+
+ * ``add`` (array) URLs to add to the field. Each
+ URL must be a valid URL to a bug-tracker, or
+ an error will be thrown.
+ * ``remove`` (array) URLs to remove from the
+ field. Invalid URLs will be ignored.
+severity string The Severity field of a bug.
+status string The status you want to change the bug to. Note
+ that if a bug is changing from open to closed,
+ you should also specify a ``resolution``.
+summary string The Summary field of the bug.
+target_milestone string The bug's Target Milestone.
+url string The "URL" field of a bug.
+version string The bug's Version field.
+whiteboard string The Status Whiteboard field of a bug.
+work_time double The number of hours worked on this bug as part
+ of this change.
+ If you set ``work_time`` but don't explicitly
+ set ``remaining_time``, then the ``work_time``
+ will be deducted from the bug's ``remaining_time``.
+===================== ======= =================================================
+
+You can also set the value of any custom field by passing its name as
+a parameter, and the value to set the field to. For multiple-selection
+fields, the value should be an array of strings.
+
+Flag change object:
+
+The following values can be specified. At least the ``status`` and one of
+``type_id``, ``id``, or ``name`` must be specified. If a ``type_id`` or
+``name`` matches a single currently set flag, the flag will be updated unless
+``new`` is specified.
+
+========== ======= ============================================================
+name type description
+========== ======= ============================================================
+name string The name of the flag that will be created or updated.
+type_id int The internal flag type ID that will be created or updated.
+ You will need to specify the ``type_id`` if more than one
+ flag type of the same name exists.
+**status** string The flags new status (i.e. "?", "+", "-" or "X" to clear a
+ flag).
+requestee string The login of the requestee if the flag type is requestable
+ to a specific user.
+id int Use ID to specify the flag to be updated. You will need to
+ specify the ``id`` if more than one flag is set of the same
+ name.
+new boolean Set to true if you specifically want a new flag to be
+ created.
+========== ======= ============================================================
+
+**Response**
+
+.. code-block:: js
+
+ {
+ "bugs" : [
+ {
+ "alias" : [],
+ "changes" : {
+ "keywords" : {
+ "added" : "funny, stupid",
+ "removed" : ""
+ },
+ "status" : {
+ "added" : "IN_PROGRESS",
+ "removed" : "CONFIRMED"
+ }
+ },
+ "id" : 35,
+ "last_change_time" : "2014-09-29T14:25:35Z"
+ }
+ ]
+ }
+
+``bugs`` (array) This points to an array of objects with the following items:
+
+================ ======== =====================================================
+name type description
+================ ======== =====================================================
+id int The ID of the bug that was updated.
+alias array The aliases of the bug that was updated, if this bug
+ has any alias.
+last_change_time datetime The exact time that this update was done at, for
+ this bug. If no update was done (that is, no fields
+ had their values changed and no comment was added)
+ then this will instead be the last time the bug was
+ updated.
+changes object The changes that were actually done on this bug. The
+ keys are the names of the fields that were changed,
+ and the values are an object with two keys:
+
+ * ``added`` (string) The values that were added to
+ this field, possibly a comma-and-space-separated
+ list if multiple values were added.
+ * ``removed`` (string) The values that were removed
+ from this field, possibly a
+ comma-and-space-separated list if multiple values
+ were removed.
+================ ======== =====================================================
+
+Currently, some fields are not tracked in changes: ``comment``,
+``comment_is_private``, and ``work_time``. This means that they will not
+show up in the return value even if they were successfully updated.
+This may change in a future version of Bugzilla.
--- /dev/null
+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.
+=============== ====== ====================================================
--- /dev/null
+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.
+=========== ====== ================================
--- /dev/null
+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,
+ "is_markdown" : true,
+ "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.
+is_markdown boolean ``true`` if this comment needs Markdown processing;
+ ``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,
+ "is_markdown" : true,
+ }
+
+``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.
+is_markdown boolean If set to ``true``, the comment has Markdown structures;
+ otherwise it is normal text.
+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.
--- /dev/null
+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.
+==== ==== ========================================
--- /dev/null
+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.
+========== ====== =============================================================
--- /dev/null
+Flag Types
+==========
+
+This part of the Bugzilla API allows you to get and create bug and attachment
+flags.
+
+.. _rest_flagtype_get:
+
+Get Flag Type
+-------------
+
+Get information about valid flag types that can be set for bugs and attachments.
+
+**Request**
+
+To get information about all flag types for a product:
+
+.. code-block:: text
+
+ GET /rest/flag_type/(product)
+
+To get information about flag_types for a product and component:
+
+.. code-block:: text
+
+ GET /rest/flag_type/(product)/(component)
+
+.. code-block:: js
+
+ {
+ "bug": [
+ {
+ "is_multiplicable": false,
+ "is_requesteeble": false,
+ "values": [
+ "X",
+ "?",
+ "+",
+ "-"
+ ],
+ "id": 11,
+ "type": "bug",
+ "is_active": true,
+ "description": "Blocks the next release",
+ "name": "blocker"
+ },
+ {
+ "is_requesteeble": false,
+ "is_multiplicable": false,
+ "is_active": true,
+ "description": "Regression found?",
+ "name": "regression",
+ "id": 10,
+ "type": "bug",
+ "values": [
+ "X",
+ "?",
+ "+",
+ "-"
+ ]
+ },
+ ],
+ "attachment": [
+ {
+ "is_requesteeble": true,
+ "is_multiplicable": true,
+ "name": "review",
+ "is_active": true,
+ "description": "Review the patch for correctness and applicability to the problem.",
+ "type": "attachment",
+ "id": 1,
+ "values": [
+ "X",
+ "?",
+ "+",
+ "-"
+ ]
+ },
+ {
+ "name": "approval",
+ "description": "Approve the patch for check-in to the tree.",
+ "is_active": true,
+ "values": [
+ "X",
+ "?",
+ "+",
+ "-"
+ ],
+ "type": "attachment",
+ "id": 3,
+ "is_multiplicable": false,
+ "is_requesteeble": false
+ }
+ ]
+ }
+
+You must pass a product name and an optional component name. If the product or
+component names contains a ``/`` character, up will need to url encode it.
+
+=========== ====== ============================================================
+name type description
+=========== ====== ============================================================
+**product** string The name of a valid product.
+component string An optional valid component name associated with the
+ product.
+=========== ====== ============================================================
+
+**Response**
+
+An object containing two items, ``bug`` and ``attachment``. Each value is an
+array of objects, containing the following items:
+
+================ ======= ======================================================
+name type description
+================ ======= ======================================================
+id int An integer ID uniquely identifying this flag type.
+name string The name for the flag type.
+type string The target of the flag type which is either ``bug``
+ or ``attachment``.
+description string The description of the flag type.
+values array String values that the user can set on the flag type.
+is_requesteeble boolean Users can ask specific other users to set flags of
+ this type.
+is_multiplicable boolean Multiple flags of this type can be set for the same
+ bug or attachment.
+================ ======= ======================================================
+
+Create Flag Type
+----------------
+
+Create a new flag type. You must be authenticated and be in the *editcomponents*
+group to perform this action.
+
+**Request**
+
+.. code-block:: text
+
+ POST /rest/flag_type
+
+.. code-block:: js
+
+ {
+ "name" : "feedback",
+ "description" : "This attachment needs feedback",
+ "inclusions" : [ "WorldControl "],
+ "target_type" : "attachment"
+ }
+
+Some params must be set, or an error will be thrown. The required params are
+marked in **bold**.
+
+=========================== ======= ===========================================
+name type description
+=========================== ======= ===========================================
+**name** string The name of the new flag type.
+**description** string A description for the flag type.
+target_type string The new flag is either for a ``bug`` or an
+ ``attachment``.
+inclusions array An array of strings or an object containing
+ product names, and optionally component
+ names. If you provide a string, the flag
+ type will be shown on all bugs in that
+ product. If you provide an object, the key
+ represents the product name, and the value
+ is the components of the product to be
+ included.
+exclusions array An array of strings or an object containing
+ product names. This uses the same format as
+ ``inclusions``. This will exclude the flag
+ from all products and components specified.
+sortkey int A number between 1 and 32767 by which this
+ type will be sorted when displayed to users
+ in a list; ignore if you don't care what
+ order the types appear in or if you want
+ them to appear in alphabetical order.
+is_active boolean Flag of this type appear in the UI and can
+ be set. Default is ``true``.
+is_requestable boolean Users can ask for flags of this type to be
+ set. Default is ``true``.
+cc_list array If the flag type is requestable, who should
+ receive e-mail notification of requests.
+ This is an array of e-mail addresses which\
+ do not need to be Bugzilla logins.
+is_specifically_requestable boolean Users can ask specific other users to
+ set flags of this type as opposed to just
+ asking the wind. Default is ``true``.
+is_multiplicable boolean Multiple flags of this type can be set on
+ the same bug. Default is ``true``.
+grant_group string The group allowed to grant/deny flags of
+ this type (to allow all users to grant/deny
+ these flags, select no group). Default is
+ no group.
+request_group string If flags of this type are requestable, the
+ group allowed to request them (to allow all
+ users to request these flags, select no
+ group). Note that the request group alone
+ has no effect if the grant group is not
+ defined! Default is no group.
+=========================== ======= ===========================================
+
+An example for ``inclusions`` and/or ``exclusions``:
+
+.. code-block:: js
+
+ [
+ "FooProduct"
+ ]
+
+ {
+ "BarProduct" : [ "C1", "C3" ],
+ "BazProduct" : [ "C7" ]
+ }
+
+This flag will be added to **all** components of ``FooProduct``, components C1
+and C3 of ``BarProduct``, and C7 of ``BazProduct``.
+
+**Response**
+
+.. code-block:: js
+
+ {
+ "id": 13
+ }
+
+======= ==== ==============================================
+name type description
+======= ==== ==============================================
+flag_id int ID of the new FlagType object is returned.
+======= ==== ==============================================
+
+.. _rest_flagtype_update:
+
+Update Flag Type
+----------------
+
+This allows you to update a flag type in Bugzilla. You must be authenticated
+and be in the *editcomponents* group to perform this action.
+
+**Request**
+
+.. code-block:: text
+
+ PUT /rest/flag_type/(id_or_name)
+
+.. code-block:: js
+
+ {
+ "ids" : [13],
+ "name" : "feedback-new",
+ "is_requestable" : false
+ }
+
+You can edit a single flag type by passing the ID or name of the flag type
+in the URL. To edit more than one flag type, you can specify addition IDs or
+flag type names using the ``ids`` or ``names`` parameters respectively.
+
+One of the below must be specified.
+
+============== ===== ==========================================================
+name type description
+============== ===== ==========================================================
+**id_or_name** mixed Integer flag type ID or name.
+**ids** array Numeric IDs of the flag types that you wish to update.
+**names** array Names of the flag types that you wish to update. If many
+ flag types have the same name, this will change **all**
+ of them.
+============== ===== ==========================================================
+
+The following parameters specify the new values you want to set for the flag
+types you are updating.
+
+=========================== ======= ===========================================
+name type description
+=========================== ======= ===========================================
+name string A short name identifying this type.
+description string A comprehensive description of this type.
+inclusions array An array of strings or an object containing
+ product names, and optionally component
+ names. If you provide a string, the flag
+ type will be shown on all bugs in that
+ product. If you provide an object, the key
+ represents the product name, and the value
+ is the components of the product to be
+ included.
+exclusions array An array of strings or an object containing
+ product names. This uses the same format as
+ ``inclusions``. This will exclude the flag
+ from all products and components specified.
+sortkey int A number between 1 and 32767 by which this
+ type will be sorted when displayed to users
+ in a list; ignore if you don't care what
+ order the types appear in or if you want
+ them to appear in alphabetical order.
+is_active boolean Flag of this type appear in the UI and can
+ be set.
+is_requestable boolean Users can ask for flags of this type to be
+ set.
+cc_list array If the flag type is requestable, who should
+ receive e-mail notification of requests.
+ This is an array of e-mail addresses
+ which do not need to be Bugzilla logins.
+is_specifically_requestable boolean Users can ask specific other users to set
+ flags of this type as opposed to just
+ asking the wind.
+is_multiplicable boolean Multiple flags of this type can be set on
+ the same bug.
+grant_group string The group allowed to grant/deny flags of
+ this type (to allow all users to grant/deny
+ these flags, select no group).
+request_group string If flags of this type are requestable, the
+ group allowed to request them (to allow all
+ users to request these flags, select no
+ group). Note that the request group alone
+ has no effect if the grant group is not
+ defined!
+=========================== ======= ===========================================
+
+An example for ``inclusions`` and/or ``exclusions``:
+
+.. code-block:: js
+
+ [
+ "FooProduct",
+ ]
+
+ {
+ "BarProduct" : [ "C1", "C3" ],
+ "BazProduct" : [ "C7" ]
+ }
+
+This flag will be added to **all** components of ``FooProduct``,
+components C1 and C3 of ``BarProduct``, and C7 of ``BazProduct``.
+
+**Response**
+
+.. code-block:: js
+
+ {
+ "flagtypes": [
+ {
+ "name": "feedback-new",
+ "changes": {
+ "is_requestable": {
+ "added": "0",
+ "removed": "1"
+ },
+ "name": {
+ "removed": "feedback",
+ "added": "feedback-new"
+ }
+ },
+ "id": 13
+ }
+ ]
+ }
+
+``flagtypes`` (array) Flag change objects containing the following items:
+
+======= ====== ================================================================
+name type description
+======= ====== ================================================================
+id int The ID of the flag type that was updated.
+name string The name of the flag type that was updated.
+changes object The changes that were actually done on this flag type.
+ The keys are the names of the fields that were changed, and the
+ values are an object with two items:
+
+ * added: (string) The value that this field was changed to.
+ * removed: (string) The value that was previously set in this
+ field.
+======= ====== ================================================================
+
+Booleans changes will be represented with the strings '1' and '0'.
--- /dev/null
+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.
+========= =====================================================================
--- /dev/null
+Groups
+======
+
+The API for creating, changing, and getting information about groups.
+
+.. _rest_group_create:
+
+Create Group
+------------
+
+This allows you to create a new group in Bugzilla. You must be authenticated and
+be in the *creategroups* group to perform this action.
+
+**Request**
+
+.. code-block:: text
+
+ POST /rest/group
+
+.. code-block:: js
+
+ {
+ "name" : "secret-group",
+ "description" : "Too secret for you!",
+ "is_active" : true
+ }
+
+Some params must be set, or an error will be thrown. The required params are
+marked in **bold**.
+
+=============== ======= =======================================================
+name type description
+=============== ======= =======================================================
+**name** string A short name for this group. Must be unique. This
+ is not usually displayed in the user interface, except
+ in a few places.
+**description** string A human-readable name for this group. Should be
+ relatively short. This is what will normally appear in
+ the UI as the name of the group.
+user_regexp string A regular expression. Any user whose Bugzilla username
+ matches this regular expression will automatically be
+ granted membership in this group.
+is_active boolean ``true`` if new group can be used for bugs, ``false``
+ if this is a group that will only contain users and no
+ bugs will be restricted to it.
+icon_url string A URL pointing to a small icon used to identify the
+ group. This icon will show up next to users' names in
+ various parts of Bugzilla if they are in this group.
+=============== ======= =======================================================
+
+**Response**
+
+.. code-block:: js
+
+ {
+ "id": 22
+ }
+
+==== ==== ==============================
+name type description
+==== ==== ==============================
+id int ID of the newly-created group.
+==== ==== ==============================
+
+.. _rest_group_update:
+
+Update Group
+------------
+
+This allows you to update a group in Bugzilla. You must be authenticated and be
+in the *creategroups* group to perform this action.
+
+**Request**
+
+To update a group using the group ID or name:
+
+.. code-block:: text
+
+ PUT /rest/group/(id_or_name)
+
+.. code-block:: js
+
+ {
+ "name" : "secret-group",
+ "description" : "Too secret for you! (updated description)",
+ "is_active" : false
+ }
+
+You can edit a single group by passing the ID or name of the group
+in the URL. To edit more than one group, you can specify addition IDs or
+group names using the ``ids`` or ``names`` parameters respectively.
+
+One of the below must be specified.
+
+============== ===== ==========================================================
+name type description
+============== ===== ==========================================================
+**id_or_name** mixed Integer group or name.
+**ids** array IDs of groups to update.
+**names** array Names of groups to update.
+============== ===== ==========================================================
+
+The following parameters specify the new values you want to set for the group(s)
+you are updating.
+
+=========== ======= ===========================================================
+name type description
+=========== ======= ===========================================================
+name string A new name for the groups. If you try to set this while
+ updating more than one group, an error will occur, as
+ group names must be unique.
+description string A new description for the groups. This is what will appear
+ in the UI as the name of the groups.
+user_regexp string A new regular expression for email. Will automatically
+ grant membership to these groups to anyone with an email
+ address that matches this perl regular expression.
+is_active boolean Set if groups are active and eligible to be used for bugs.
+ ``true`` if bugs can be restricted to this group, ``false``
+ otherwise.
+icon_url string A URL pointing to an icon that will appear next to the name
+ of users who are in this group.
+=========== ======= ===========================================================
+
+**Response**
+
+.. code-block:: js
+
+ {
+ "groups": [
+ {
+ "changes": {
+ "description": {
+ "added": "Too secret for you! (updated description)",
+ "removed": "Too secret for you!"
+ },
+ "is_active": {
+ "removed": "1",
+ "added": "0"
+ }
+ },
+ "id": "22"
+ }
+ ]
+ }
+
+``groups`` (array) Group change objects, each containing the following items:
+
+======= ====== ================================================================
+name type description
+======= ====== ================================================================
+id int The ID of the group that was updated.
+changes object The changes that were actually done on this group. The
+ keys are the names of the fields that were changed, and the
+ values are an object with two items:
+
+ * added: (string) The values that were added to this field,
+ possibly a comma-and-space-separated list if multiple values
+ were added.
+ * removed: (string) The values that were removed from this
+ field, possibly a comma-and-space-separated list if multiple
+ values were removed.
+======= ====== ================================================================
+
+.. _rest_group_get:
+
+Get Group
+---------
+
+Returns information about Bugzilla groups.
+
+**Request**
+
+To return information about a specific group ID or name:
+
+.. code-block:: text
+
+ GET /rest/group/(id_or_name)
+
+You can also return information about more than one specific group by using the
+following in your query string:
+
+.. code-block:: text
+
+ GET /rest/group?ids=1&ids=2&ids=3
+ GET /group?names=ProductOne&names=Product2
+
+If neither IDs nor names are passed, and you are in the creategroups or
+editusers group, then all groups will be retrieved. Otherwise, only groups
+that you have bless privileges for will be returned.
+
+========== ======= ============================================================
+name type description
+========== ======= ============================================================
+id_or_name mixed Integer group ID or name.
+ids array Integer IDs of groups.
+names array Names of groups.
+membership boolean Set to 1 then a list of members of the passed groups names
+ and IDs will be returned.
+========== ======= ============================================================
+
+**Response**
+
+.. code-block:: js
+
+ {
+ "groups": [
+ {
+ "membership": [
+ {
+ "real_name": "Bugzilla User",
+ "can_login": true,
+ "name": "user@bugzilla.org",
+ "login_denied_text": "",
+ "id": 85,
+ "email_enabled": false,
+ "email": "user@bugzilla.org"
+ },
+ ],
+ "is_active": true,
+ "description": "Test Group",
+ "user_regexp": "",
+ "is_bug_group": true,
+ "name": "TestGroup",
+ "id": 9
+ }
+ ]
+ }
+
+If the user is a member of the *creategroups* group they will receive
+information about all groups or groups matching the criteria that they passed.
+You have to be in the creategroups group unless you're requesting membership
+information.
+
+If the user is not a member of the *creategroups* group, but they are in the
+"editusers" group or have bless privileges to the groups they require
+membership information for, the is_active, is_bug_group and user_regexp values
+are not supplied.
+
+The return value will be an object containing group names as the keys; each
+value will be an object that describes the group and has the following items:
+
+============ ====== ===========================================================
+name type description
+============ ====== ===========================================================
+id int The unique integer ID that Bugzilla uses to identify this
+ group. Even if the name of the group changes, this ID will
+ stay the same.
+name string The name of the group.
+description string The description of the group.
+is_bug_group int Whether this group is to be used for bug reports or is
+ only administrative specific.
+user_regexp string A regular expression that allows users to be added to
+ this group if their login matches.
+is_active int Whether this group is currently active or not.
+users array User objects that are members of this group; only
+ returned if the user sets the ``membership`` parameter to
+ 1. Each user object has the items describe in the User
+ object below.
+============ ====== ===========================================================
+
+User object:
+
+============= ======= =========================================================
+name type description
+============= ======= =========================================================
+id int The ID of the user.
+real_name string The actual name of the user.
+email string The email address of the user.
+name string The login name of the user. Note that in some situations
+ this is different than their email.
+can_login boolean A boolean value to indicate if the user can login into
+ bugzilla.
+email_enabled boolean A boolean value to indicate if bug-related mail will
+ be sent to the user or not.
+disabled_text string A text field that holds the reason for disabling a user
+ from logging into Bugzilla. If empty, then the user
+ account is enabled; otherwise it is disabled/closed.
+============= ======= =========================================================
--- /dev/null
+Core API v1
+===========
+
+.. toctree::
+
+ general
+ attachment
+ bug
+ bug-user-last-visit
+ bugzilla
+ classification
+ comment
+ component
+ field
+ flagtype
+ group
+ product
+ user
--- /dev/null
+Products
+========
+
+This part of the Bugzilla API allows you to list the available products and
+get information about them.
+
+.. _rest_product_list:
+
+List Products
+-------------
+
+Returns a list of the IDs of the products the user can search on.
+
+**Request**
+
+To get a list of product IDs a user can select such as for querying bugs:
+
+.. code-block:: text
+
+ GET /rest/product_selectable
+
+To get a list of product IDs a user can enter a bug against:
+
+.. code-block:: text
+
+ GET /rest/product_enterable
+
+To get a list of product IDs a user can search or enter bugs against.
+
+.. code-block:: text
+
+ GET /rest/product_accessible
+
+**Response**
+
+.. code-block:: js
+
+ {
+ "ids": [
+ "2",
+ "3",
+ "19",
+ "1",
+ "4"
+ ]
+ }
+
+==== ===== ======================================
+name type description
+==== ===== ======================================
+ids array List of integer product IDs.
+==== ===== ======================================
+
+.. _rest_product_get:
+
+Get Product
+-----------
+
+Returns a list of information about the products passed to it.
+
+**Request**
+
+To return information about a specific type of products such as
+``accessible``, ``selectable``, or ``enterable``:
+
+.. code-block:: text
+
+ GET /rest/product?type=accessible
+
+To return information about a specific product by ``id`` or ``name``:
+
+.. code-block:: text
+
+ GET /rest/product/(id_or_name)
+
+You can also return information about more than one product by using the
+following parameters in your query string:
+
+.. code-block:: text
+
+ GET /rest/product?ids=1&ids=2&ids=3
+ GET /rest/product?names=ProductOne&names=Product2
+
+========== ====== =============================================================
+name type description
+========== ====== =============================================================
+id_or_name mixed Integer product ID or product name.
+ids array Product IDs
+names array Product names
+type string The group of products to return. Valid values are
+ ``accessible`` (default), ``selectable``, and ``enterable``.
+ ``type`` can be a single value or an array of values if more
+ than one group is needed with duplicates removed.
+========== ====== =============================================================
+
+**Response**
+
+.. code-block:: js
+
+ {
+ "products": [
+ {
+ "id": 1,
+ "default_milestone": "---",
+ "components": [
+ {
+ "is_active": true,
+ "default_assigned_to": "admin@bugzilla.org",
+ "id": 1,
+ "sort_key": 0,
+ "name": "TestComponent",
+ "flag_types": {
+ "bug": [
+ {
+ "is_active": true,
+ "grant_group": null,
+ "cc_list": "",
+ "is_requestable": true,
+ "id": 3,
+ "is_multiplicable": true,
+ "name": "needinfo",
+ "request_group": null,
+ "is_requesteeble": true,
+ "sort_key": 0,
+ "description": "needinfo"
+ }
+ ],
+ "attachment": [
+ {
+ "description": "Review",
+ "is_multiplicable": true,
+ "name": "review",
+ "is_requesteeble": true,
+ "request_group": null,
+ "sort_key": 0,
+ "cc_list": "",
+ "grant_group": null,
+ "is_requestable": true,
+ "id": 2,
+ "is_active": true
+ }
+ ]
+ },
+ "default_qa_contact": "",
+ "description": "This is a test component."
+ }
+ ],
+ "is_active": true,
+ "classification": "Unclassified",
+ "versions": [
+ {
+ "id": 1,
+ "name": "unspecified",
+ "is_active": true,
+ "sort_key": 0
+ }
+ ],
+ "description": "This is a test product.",
+ "has_unconfirmed": true,
+ "milestones": [
+ {
+ "name": "---",
+ "is_active": true,
+ "sort_key": 0,
+ "id": 1
+ }
+ ],
+ "name": "TestProduct"
+ }
+ ]
+ }
+
+``products`` (array) Each product object has the following items:
+
+================= ======= =====================================================
+name type description
+================= ======= =====================================================
+id int An integer ID uniquely identifying the product in
+ this installation only.
+name string The name of the product. This is a unique identifier
+ for the product.
+description string A description of the product, which may contain HTML.
+is_active boolean A boolean indicating if the product is active.
+default_milestone string The name of the default milestone for the product.
+has_unconfirmed boolean Indicates whether the UNCONFIRMED bug status is
+ available for this product.
+classification string The classification name for the product.
+components array Each component object has the items described in the
+ Component object below.
+versions array Each object describes a version, and has the
+ following items: ``name``, ``sort_key`` and
+ ``is_active``.
+milestones array Each object describes a milestone, and has the
+ following items: ``name``, ``sort_key`` and
+ ``is_active``.
+================= ======= =====================================================
+
+If the user tries to access a product that is not in the list of accessible
+products for the user, or a product that does not exist, that is silently
+ignored, and no information about that product is returned.
+
+Component object:
+
+=================== ======= ===================================================
+name type description
+=================== ======= ===================================================
+id int An integer ID uniquely identifying the component in
+ this installation only.
+name string The name of the component. This is a unique
+ identifier for this component.
+description string A description of the component, which may contain
+ HTML.
+default_assigned_to string The login name of the user to whom new bugs
+ will be assigned by default.
+default_qa_contact string The login name of the user who will be set as
+ the QA Contact for new bugs by default. Empty
+ string if the QA contact is not defined.
+sort_key int Components, when displayed in a list, are sorted
+ first by this integer and then secondly by their
+ name.
+is_active boolean A boolean indicating if the component is active.
+ Inactive components are not enabled for new bugs.
+flag_types object An object containing two items ``bug`` and
+ ``attachment`` that each contains an array of
+ objects, where each describes a flagtype. The
+ flagtype items are described in the Flagtype
+ object below.
+=================== ======= ===================================================
+
+Flagtype object:
+
+================ ======= ======================================================
+name type description
+================ ======= ======================================================
+id int Returns the ID of the flagtype.
+name string Returns the name of the flagtype.
+description string Returns the description of the flagtype.
+cc_list string Returns the concatenated CC list for the flagtype, as
+ a single string.
+sort_key int Returns the sortkey of the flagtype.
+is_active boolean Returns whether the flagtype is active or disabled.
+ Flags being in a disabled flagtype are not deleted.
+ It only prevents you from adding new flags to it.
+is_requestable boolean Returns whether you can request for the given
+ flagtype (i.e. whether the '?' flag is available or
+ not).
+is_requesteeble boolean Returns whether you can ask someone specifically
+ or not.
+is_multiplicable boolean Returns whether you can have more than one
+ flag for the given flagtype in a given bug/attachment.
+grant_group int the group ID that is allowed to grant/deny flags of
+ this type. If the item is not included all users are
+ allowed to grant/deny this flagtype.
+request_group int The group ID that is allowed to request the flag if
+ the flag is of the type requestable. If the item is
+ not included all users are allowed request this
+ flagtype.
+================ ======= ======================================================
+
+.. _rest_product_create:
+
+Create Product
+--------------
+
+This allows you to create a new product in Bugzilla.
+
+**Request**
+
+.. code-block:: text
+
+ POST /rest/product
+
+.. code-block:: js
+
+ {
+ "name" : "AnotherProduct",
+ "description" : "Another Product",
+ "classification" : "Unclassified",
+ "is_open" : false,
+ "has_unconfirmed" : false,
+ "version" : "unspecified"
+ }
+
+Some params must be set, or an error will be thrown. The required params are
+marked in bold.
+
+================= ======= =====================================================
+name type description
+================= ======= =====================================================
+**name** string The name of this product. Must be globally unique
+ within Bugzilla.
+**description** string A description for this product. Allows some simple
+ HTML.
+**version** string The default version for this product.
+has_unconfirmed boolean Allow the UNCONFIRMED status to be set on bugs in
+ this product. Default: true.
+classification string The name of the Classification which contains this
+ product.
+default_milestone string The default milestone for this product. Default
+ '---'.
+is_open boolean ``true`` if the product is currently allowing bugs
+ to be entered into it. Default: ``true``.
+create_series boolean ``true`` if you want series for New Charts to be
+ created for this new product. Default: ``true``.
+================= ======= =====================================================
+
+**Response**
+
+.. code-block:: js
+
+ {
+ "id": 20
+ }
+
+Returns an object with the following items:
+
+==== ==== =====================================
+name type description
+==== ==== =====================================
+id int ID of the newly-filed product.
+==== ==== =====================================
+
+.. _rest_product_update:
+
+Update Product
+--------------
+
+This allows you to update a product in Bugzilla.
+
+**Request**
+
+.. code-block:: text
+
+ PUT /rest/product/(id_or_name)
+
+You can edit a single product by passing the ID or name of the product
+in the URL. To edit more than one product, you can specify addition IDs or
+product names using the ``ids`` or ``names`` parameters respectively.
+
+.. code-block:: js
+
+ {
+ "ids" : [123],
+ "name" : "BarName",
+ "has_unconfirmed" : false
+ }
+
+One of the below must be specified.
+
+============== ===== ==========================================================
+name type description
+============== ===== ==========================================================
+**id_or_name** mixed Integer product ID or name.
+**ids** array Numeric IDs of the products that you wish to update.
+**names** array Names of the products that you wish to update.
+============== ===== ==========================================================
+
+The following parameters specify the new values you want to set for the product(s)
+you are updating.
+
+================= ======= =====================================================
+name type description
+================= ======= =====================================================
+name string A new name for this product. If you try to set this
+ while updating more than one product, an error will
+ occur, as product names must be unique.
+default_milestone string When a new bug is filed, what milestone does it
+ get by default if the user does not choose one? Must
+ represent a milestone that is valid for this product.
+description string Update the long description for these products to
+ this value.
+has_unconfirmed boolean Allow the UNCONFIRMED status to be set on bugs in
+ products.
+is_open boolean ``true`` if the product is currently allowing bugs
+ to be entered into it, ``false`` otherwise.
+================= ======= =====================================================
+
+**Response**
+
+.. code-block:: js
+
+ {
+ "products" : [
+ {
+ "id" : 123,
+ "changes" : {
+ "name" : {
+ "removed" : "FooName",
+ "added" : "BarName"
+ },
+ "has_unconfirmed" : {
+ "removed" : "1",
+ "added" : "0"
+ }
+ }
+ }
+ ]
+ }
+
+``products`` (array) Product change objects containing the following items:
+
+======= ====== ================================================================
+name type description
+======= ====== ================================================================
+id int The ID of the product that was updated.
+changes object The changes that were actually done on this product. The
+ keys are the names of the fields that were changed, and the
+ values are an object with two items:
+
+ * added: (string) The value that this field was changed to.
+ * removed: (string) The value that was previously set in this
+ field.
+======= ====== ================================================================
+
+Booleans will be represented with the strings '1' and '0' for changed values
+as they are stored as strings in the database currently.
--- /dev/null
+Users
+=====
+
+This part of the Bugzilla API allows you to create user accounts, get information
+about user accounts and to log in or out using an existing account.
+
+.. _rest_user_login:
+
+Login
+-----
+
+Logging in with a username and password is required for many Bugzilla
+installations, in order to search for private bugs, post new bugs, etc. This
+method allows you to retrieve a token that can be used as authentication for
+subsequent API calls. Otherwise yuou will need to pass your ``login`` and
+``password`` with each call.
+
+This method will be going away in the future in favor of using *API keys*.
+
+**Request**
+
+.. code-block:: text
+
+ GET /rest/login?login=foo@example.com&password=toosecrettoshow
+
+============== ======= ========================================================
+name type description
+============== ======= ========================================================
+**login** string The user's login name.
+**password** string The user's password.
+restrict_login boolean If set to a true value, the token returned by this
+ method will only be valid from the IP address which
+ called this method.
+============== ======= ========================================================
+
+**Response**
+
+.. code-block:: js
+
+ {
+ "token": "786-OLaWfBisMY",
+ "id": 786
+ }
+
+======== ====== ===============================================================
+name type description
+======== ====== ===============================================================
+id int Numeric ID of the user that was logged in.
+token string Token which can be passed in the parameters as
+ authentication in other calls. The token can be sent along
+ with any future requests to the webservice, for the duration
+ of the session, i.e. til :ref:`rest_user_logout` is called.
+======== ====== ===============================================================
+
+.. _rest_user_logout:
+
+Logout
+------
+
+Log out the user. Basically it invalidates the token provided so it cannot be
+re-used. Does nothing if the token is not in use. Will also clear any existing
+authentication cookies the client may still have stored.
+
+**Request**
+
+.. code-block:: text
+
+ GET /rest/logout?token=1234-VWvO51X69r
+
+===== ====== ===================================================
+name type description
+===== ====== ===================================================
+token string The user's token used for authentication.
+===== ====== ===================================================
+
+.. _rest_user_valid_login:
+
+Valid Login
+-----------
+
+This method will verify whether a client's cookies or current login token is
+still valid or have expired. A valid username that matches must be provided as
+well.
+
+**Request**
+
+.. code-block:: text
+
+ GET /rest/valid_login?login=foo@example.com&token=1234-VWvO51X69r
+
+========= ======= =============================================================
+name type description
+========= ======= =============================================================
+**login** string The login name that matches the provided cookies or token.
+token string Persistent login token currently being used for
+ authentication.
+========= ======= =============================================================
+
+**Response**
+
+Returns true/false depending on if the current token is valid for the provided
+username.
+
+.. _rest_user_create:
+
+Create User
+-----------
+
+Creates a user account directly in Bugzilla, password and all. Instead of this,
+you should use **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 authenticated and be in the *editusers* group
+to perform this action.
+
+**Request**
+
+.. code-block:: text
+
+ POST /rest/user
+
+.. code-block:: js
+
+ {
+ "email" : "user@bugzilla.org",
+ "full_name" : "Test User",
+ "password" : "K16ldRr922I1"
+ }
+
+========== ====== =============================================================
+name type description
+========== ====== =============================================================
+**email** string The email address for the new user.
+full_name string The user's full name. Will be set to empty if not specified.
+password string The password for the new user account, in plain text. It
+ will be stripped of leading and trailing whitespace. If
+ blank or not specified, the new created account will
+ exist in Bugzilla but will not be allowed to log in
+ using DB authentication until a password is set either
+ by the user (through resetting their password) or by the
+ administrator.
+========== ====== =============================================================
+
+**Response**
+
+.. code-block:: js
+
+ {
+ "id": 58707
+ }
+
+==== ==== ============================================
+name type desciption
+==== ==== ============================================
+id int The numeric ID of the user that was created.
+==== ==== ============================================
+
+.. _rest_user_update:
+
+Update User
+-----------
+
+Updates an existing user account in Bugzilla. You must be authenticated and be
+in the *editusers* group to perform this action.
+
+**Request**
+
+.. code-block:: text
+
+ PUT /rest/user/(id_or_name)
+
+You can edit a single user by passing the ID or login name of the user
+in the URL. To edit more than one user, you can specify addition IDs or
+login names using the ``ids`` or ``names`` parameters respectively.
+
+================= ======= =====================================================
+ name type description
+================= ======= =====================================================
+**id_or_name** mixed Either the ID or the login name of the user to
+ update.
+**ids** array Additional IDs of users to update.
+**names** array Additional login names of users to update.
+full_name string The new name of the user.
+email string The email of the user. Note that email used to
+ login to bugzilla. Also note that you can only
+ update one user at a time when changing the login
+ name / email. (An error will be thrown if you try to
+ update this field for multiple users at once.)
+password string The password of the user.
+email_enabled boolean A boolean value to enable/disable sending
+ bug-related mail to the user.
+login_denied_text string A text field that holds the reason for disabling a
+ user from logging into Bugzilla. If empty, then the
+ user account is enabled; otherwise it is
+ disabled/closed.
+groups object These specify the groups that this user is directly
+ a member of. To set these, you should pass an object
+ as the value. The object's items are described in
+ the Groups update objects below.
+bless_groups object This is the same as groups but affects what groups
+ a user has direct membership to bless that group.
+ It takes the same inputs as groups.
+================= ======= =====================================================
+
+Groups and bless groups update object:
+
+====== ===== ==================================================================
+name type description
+====== ===== ==================================================================
+add array The group IDs or group names that the user should be added to.
+remove array The group IDs or group names that the user should be removed from.
+set array Integers or strings which are an exact set of group IDs and group
+ names that the user should be a member of. This does not remove
+ groups from the user when the person making the change does not
+ have the bless privilege for the group.
+====== ===== ==================================================================
+
+If you specify ``set``, then ``add`` and ``remove`` will be ignored. A group in
+both the ``add`` and ``remove`` list will be added. Specifying a group that the
+user making the change does not have bless rights will generate an error.
+
+**Response**
+
+* users: (array) List of user change objects with the following items:
+
+======= ====== ================================================================
+name type description
+======= ====== ================================================================
+id int The ID of the user that was updated.
+changes object The changes that were actually done on this user. The keys
+ are the names of the fields that were changed, and the values
+ are an object with two items:
+
+ * added: (string) The values that were added to this field,
+ possibly a comma-and-space-separated list if multiple values
+ were added.
+ * removed: (string) The values that were removed from this
+ field, possibly a comma-and-space-separated list if multiple
+ values were removed.
+======= ====== ================================================================
+
+.. _rest_user_get:
+
+Get User
+--------
+
+Gets information about user accounts in Bugzilla.
+
+**Request**
+
+To get information about a single user in Bugzilla:
+
+.. code-block:: text
+
+ GET /rest/user/(id_or_name)
+
+To get multiple users by name or ID:
+
+.. code-block:: text
+
+ GET /rest/user?names=foo@bar.com&name=test@bugzilla.org
+ GET /rest/user?ids=123&ids=321
+
+To get user matching a search string:
+
+.. code-block:: text
+
+ GET /rest/user?match=foo
+
+To get user by using an integer ID value or by using ``match``, you must be
+authenticated.
+
+================ ======= ======================================================
+name type description
+================ ======= ======================================================
+id_or_name mixed An integer user ID or login name of the user.
+ids array Integer user IDs. Logged=out users cannot pass
+ this parameter to this function. If they try,
+ they will get an error. Logged=in users will get
+ an error if they specify the ID of a user they
+ cannot see.
+names array Login names.
+match array This works just like "user matching" in Bugzilla
+ itself. Users will be returned whose real name
+ or login name contains any one of the specified
+ strings. Users that you cannot see will not be
+ included in the returned list.
+
+ Most installations have a limit on how many
+ matches are returned for each string; the default
+ is 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. (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.)
+limit int Limit the number of users matched by the
+ ``match`` parameter. If the value is greater than the
+ system limit, the system limit will be used.
+ This parameter is only valid when using the ``match``
+ parameter.
+group_ids array Numeric IDs for groups that a user can be in.
+groups array Names of groups that a user can be in. If
+ ``group_ids`` or ``groups`` are specified, they
+ limit the return value to users who are in *any*
+ of the groups specified.
+include_disabled boolean By default, when using the ``match`` parameter,
+ disabled users are excluded from the returned
+ results unless their full username is identical
+ to the match string. Setting ``include_disabled`` to
+ ``true`` will include disabled users in the returned
+ results even if their username doesn't fully match
+ the input string.
+================ ======= ======================================================
+
+**Response**
+
+* users: (array) Each object describes a user and has the following items:
+
+================= ======= =====================================================
+name type description
+================= ======= =====================================================
+id int The unique integer ID that Bugzilla uses to represent
+ this user. Even if the user's login name changes,
+ this will not change.
+real_name string The actual name of the user. May be blank.
+email string The email address of the user.
+name string The login name of the user. Note that in some
+ situations this is different than their email.
+can_login boolean A boolean value to indicate if the user can login
+ into bugzilla.
+email_enabled boolean A boolean value to indicate if bug-related mail will
+ be sent to the user or not.
+login_denied_text string A text field that holds the reason for disabling a
+ user from logging into Bugzilla. If empty then the
+ user account is enabled; otherwise it is
+ disabled/closed.
+groups array Groups the user is a member of. If the currently
+ logged in user is querying their own account or is a
+ member of the 'editusers' group, the array will
+ contain all the groups that the user is a member of.
+ Otherwise, the array will only contain groups that
+ the logged in user can bless. Each object describes
+ the group and contains the items described in the
+ Group object below.
+saved_searches array User's saved searches, each having the following
+ Search object items described below.
+saved_reports array User's saved reports, each having the following
+ Search object items described below.
+================= ======= =====================================================
+
+Group object:
+
+=========== ====== ============================================================
+name type description
+=========== ====== ============================================================
+id int The group ID
+name string The name of the group
+description string The description for the group
+=========== ====== ============================================================
+
+Search object:
+
+===== ====== ==================================================================
+name type description
+===== ====== ==================================================================
+id int An integer ID uniquely identifying the saved report.
+name string The name of the saved report.
+query string The CGI parameters for the saved report.
+===== ====== ==================================================================
+
+If you are not authenticated when you call this function, you will only be
+returned the ``id``, ``name``, and ``real_name`` items. If you are authenticated
+and not in 'editusers' group, you will only be returned the ``id``, ``name``,
+``real_name``, ``email``, ``can_login``, and ``groups`` items. The groups
+returned are filtered based on your permission to bless each group. The
+``saved_searches`` and ``saved_reports`` items are only returned if you are
+querying your own account, even if you are in the editusers group.
last time you compiled the documentation):
.. toctree::
- :maxdepth: 1
:glob:
- extensions/*
+ extensions/*/*
security
using
extensions
+ api
customization
patches
troubleshooting
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.
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.
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 {
$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);
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');
--- /dev/null
+Example API v1
+==============
+
+Here is where you place your API docs for the Example extension.
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`.
-
projects / thirdparty / bugzilla.git / commitdiff
