diff options
| author | David Lawrence <dkl@mozilla.com> | 2014-11-26 16:37:59 +0100 |
|---|---|---|
| committer | David Lawrence <dkl@mozilla.com> | 2014-11-26 16:37:59 +0100 |
| commit | ad031a17fbd31766c4a5d1fe8894178784262d3e (patch) | |
| tree | 3d7badd3a23338cbcc3c0e5de66cb29bd3c2eda2 /docs/en/rst | |
| parent | 649a38910889a9945e2ef22f5d6ff4d32fceeba6 (diff) | |
| download | bugzilla-ad031a17fbd31766c4a5d1fe8894178784262d3e.tar.gz bugzilla-ad031a17fbd31766c4a5d1fe8894178784262d3e.tar.xz | |
Bug 1038275: Comprehensible documentation for the REST API
r=gerv,a=glob
Diffstat (limited to 'docs/en/rst')
| -rw-r--r-- | docs/en/rst/api.rst | 11 | ||||
| -rw-r--r-- | docs/en/rst/api/core/v1/attachment.rst | 357 | ||||
| -rw-r--r-- | docs/en/rst/api/core/v1/bug-user-last-visit.rst | 111 | ||||
| -rw-r--r-- | docs/en/rst/api/core/v1/bug.rst | 991 | ||||
| -rw-r--r-- | docs/en/rst/api/core/v1/bugzilla.rst | 302 | ||||
| -rw-r--r-- | docs/en/rst/api/core/v1/classification.rst | 80 | ||||
| -rw-r--r-- | docs/en/rst/api/core/v1/comment.rst | 248 | ||||
| -rw-r--r-- | docs/en/rst/api/core/v1/component.rst | 65 | ||||
| -rw-r--r-- | docs/en/rst/api/core/v1/field.rst | 240 | ||||
| -rw-r--r-- | docs/en/rst/api/core/v1/flagtype.rst | 373 | ||||
| -rw-r--r-- | docs/en/rst/api/core/v1/general.rst | 255 | ||||
| -rw-r--r-- | docs/en/rst/api/core/v1/group.rst | 278 | ||||
| -rw-r--r-- | docs/en/rst/api/core/v1/index.rst | 18 | ||||
| -rw-r--r-- | docs/en/rst/api/core/v1/product.rst | 416 | ||||
| -rw-r--r-- | docs/en/rst/api/core/v1/user.rst | 380 | ||||
| -rw-r--r-- | docs/en/rst/extensions.rst | 3 | ||||
| -rw-r--r-- | docs/en/rst/index.rst | 1 | ||||
| -rw-r--r-- | docs/en/rst/installation.rst | 8 |
18 files changed, 4131 insertions, 6 deletions
diff --git a/docs/en/rst/api.rst b/docs/en/rst/api.rst new file mode 100644 index 000000000..99cb94c6d --- /dev/null +++ b/docs/en/rst/api.rst @@ -0,0 +1,11 @@ +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* diff --git a/docs/en/rst/api/core/v1/attachment.rst b/docs/en/rst/api/core/v1/attachment.rst new file mode 100644 index 000000000..22a57af60 --- /dev/null +++ b/docs/en/rst/api/core/v1/attachment.rst @@ -0,0 +1,357 @@ +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. +================ ======== ===================================================== diff --git a/docs/en/rst/api/core/v1/bug-user-last-visit.rst b/docs/en/rst/api/core/v1/bug-user-last-visit.rst new file mode 100644 index 000000000..919744968 --- /dev/null +++ b/docs/en/rst/api/core/v1/bug-user-last-visit.rst @@ -0,0 +1,111 @@ +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. +============= ======== ============================================ diff --git a/docs/en/rst/api/core/v1/bug.rst b/docs/en/rst/api/core/v1/bug.rst new file mode 100644 index 000000000..6b9be97cb --- /dev/null +++ b/docs/en/rst/api/core/v1/bug.rst @@ -0,0 +1,991 @@ +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. diff --git a/docs/en/rst/api/core/v1/bugzilla.rst b/docs/en/rst/api/core/v1/bugzilla.rst new file mode 100644 index 000000000..2dd40e0cb --- /dev/null +++ b/docs/en/rst/api/core/v1/bugzilla.rst @@ -0,0 +1,302 @@ +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. +=============== ====== ==================================================== diff --git a/docs/en/rst/api/core/v1/classification.rst b/docs/en/rst/api/core/v1/classification.rst new file mode 100644 index 000000000..8b5003d39 --- /dev/null +++ b/docs/en/rst/api/core/v1/classification.rst @@ -0,0 +1,80 @@ +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. +=========== ====== ================================ diff --git a/docs/en/rst/api/core/v1/comment.rst b/docs/en/rst/api/core/v1/comment.rst new file mode 100644 index 000000000..54048122a --- /dev/null +++ b/docs/en/rst/api/core/v1/comment.rst @@ -0,0 +1,248 @@ +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. diff --git a/docs/en/rst/api/core/v1/component.rst b/docs/en/rst/api/core/v1/component.rst new file mode 100644 index 000000000..aceada1a7 --- /dev/null +++ b/docs/en/rst/api/core/v1/component.rst @@ -0,0 +1,65 @@ +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. +==== ==== ======================================== diff --git a/docs/en/rst/api/core/v1/field.rst b/docs/en/rst/api/core/v1/field.rst new file mode 100644 index 000000000..d97aa3050 --- /dev/null +++ b/docs/en/rst/api/core/v1/field.rst @@ -0,0 +1,240 @@ +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. +========== ====== ============================================================= diff --git a/docs/en/rst/api/core/v1/flagtype.rst b/docs/en/rst/api/core/v1/flagtype.rst new file mode 100644 index 000000000..994ac27c8 --- /dev/null +++ b/docs/en/rst/api/core/v1/flagtype.rst @@ -0,0 +1,373 @@ +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'. diff --git a/docs/en/rst/api/core/v1/general.rst b/docs/en/rst/api/core/v1/general.rst new file mode 100644 index 000000000..06ef5b2fb --- /dev/null +++ b/docs/en/rst/api/core/v1/general.rst @@ -0,0 +1,255 @@ +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. +========= ===================================================================== diff --git a/docs/en/rst/api/core/v1/group.rst b/docs/en/rst/api/core/v1/group.rst new file mode 100644 index 000000000..e2c595240 --- /dev/null +++ b/docs/en/rst/api/core/v1/group.rst @@ -0,0 +1,278 @@ +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. +============= ======= ========================================================= diff --git a/docs/en/rst/api/core/v1/index.rst b/docs/en/rst/api/core/v1/index.rst new file mode 100644 index 000000000..933aeed96 --- /dev/null +++ b/docs/en/rst/api/core/v1/index.rst @@ -0,0 +1,18 @@ +Core API v1 +=========== + +.. toctree:: + + general + attachment + bug + bug-user-last-visit + bugzilla + classification + comment + component + field + flagtype + group + product + user diff --git a/docs/en/rst/api/core/v1/product.rst b/docs/en/rst/api/core/v1/product.rst new file mode 100644 index 000000000..95726a3a8 --- /dev/null +++ b/docs/en/rst/api/core/v1/product.rst @@ -0,0 +1,416 @@ +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. diff --git a/docs/en/rst/api/core/v1/user.rst b/docs/en/rst/api/core/v1/user.rst new file mode 100644 index 000000000..e27211a7f --- /dev/null +++ b/docs/en/rst/api/core/v1/user.rst @@ -0,0 +1,380 @@ +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. diff --git a/docs/en/rst/extensions.rst b/docs/en/rst/extensions.rst index 91eaab952..fa444a052 100644 --- a/docs/en/rst/extensions.rst +++ b/docs/en/rst/extensions.rst @@ -5,7 +5,6 @@ Your Bugzilla installation has the following extensions available (as of the last time you compiled the documentation): .. toctree:: - :maxdepth: 1 :glob: - extensions/* + extensions/*/* diff --git a/docs/en/rst/index.rst b/docs/en/rst/index.rst index f2bd14f18..2da16e223 100644 --- a/docs/en/rst/index.rst +++ b/docs/en/rst/index.rst @@ -16,6 +16,7 @@ Bugzilla Documentation security using extensions + api customization patches troubleshooting diff --git a/docs/en/rst/installation.rst b/docs/en/rst/installation.rst index ca69667f4..5c0aa2de5 100644 --- a/docs/en/rst/installation.rst +++ b/docs/en/rst/installation.rst @@ -748,8 +748,8 @@ Without this directive, Apache will not follow symbolic links to places outside its own directory structure, and you will be unable to run Bugzilla. -Apache *httpd * log files with bugzilla -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Apache *httpd* log files with bugzilla +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For security reasons it is recommended to prevent Apache from logging query strings. @@ -761,8 +761,8 @@ reasons we recommend configuring Apache to not include the query-string in its l files to avoid storing passwords in clear text on the server. #. Load :file:`httpd.conf` or :file:`apache2.conf` in your editor. - In most of the Linux distributions this file is found in :folder:`/etc/httpd/conf/httpd.conf` - or in :folder:`/etc/apache2/apache2.conf`. + In most of the Linux distributions this file is found in :folder:`/etc/httpd/conf/httpd.conf` + or in :folder:`/etc/apache2/apache2.conf`. #. Find the following line in the above mentioned file. LogFormat "%v:%p %h %l %u %t \"%r\" %>s %O \"%{Referer}i\" \"%{User-Agent}i\"" vhost_combined. |