Bommels05/Mozilla
Bommels05/Mozilla
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Bug 1038275: Comprehensible documentation for the REST API

Browse Source 
r=gerv,a=glob


git-svn-id: svn://10.0.0.236/trunk@265691 18797224-902f-48f8-a5cc-f745e15eee43
This commit is contained in:
bzrmirror%bugzilla.org 2014-11-26 15:46:00 +00:00
parent 5154d0fab9
commit 3461a135ce
24 changed files with 4182 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
mozilla/webtools/bugzilla/.bzrrev
View File

@ -1 +1 @@
9224 9225

2
mozilla/webtools/bugzilla/.gitrev
View File

@ -1 +1 @@
649a38910889a9945e2ef22f5d6ff4d32fceeba6 ad031a17fbd31766c4a5d1fe8894178784262d3e

8
mozilla/webtools/bugzilla/Bugzilla/Install/Requirements.pm
View File

@ -403,6 +403,14 @@ sub OPTIONAL_MODULES {
module => 'Text::Markdown', module => 'Text::Markdown',
version => '1.0.26', version => '1.0.26',
feature => ['markdown'], feature => ['markdown'],
},
# Documentation
{
package => 'File-Copy-Recursive',
module => 'File::Copy::Recursive',
version => 0,
feature => ['documentation'],
} }
); );

11
mozilla/webtools/bugzilla/docs/en/rst/api.rst Normal file
View File

@ -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*

357
mozilla/webtools/bugzilla/docs/en/rst/api/core/v1/attachment.rst Normal file
View File

@ -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.
================ ======== =====================================================

111
mozilla/webtools/bugzilla/docs/en/rst/api/core/v1/bug-user-last-visit.rst Normal file
View File

@ -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.
============= ======== ============================================

991
mozilla/webtools/bugzilla/docs/en/rst/api/core/v1/bug.rst Normal file
View File

@ -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.

302
mozilla/webtools/bugzilla/docs/en/rst/api/core/v1/bugzilla.rst Normal file
View File

@ -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.
=============== ====== ====================================================

80
mozilla/webtools/bugzilla/docs/en/rst/api/core/v1/classification.rst Normal file
View File

@ -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.
=========== ====== ================================

248
mozilla/webtools/bugzilla/docs/en/rst/api/core/v1/comment.rst Normal file
View File

@ -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.

65
mozilla/webtools/bugzilla/docs/en/rst/api/core/v1/component.rst Normal file
View File

@ -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.
==== ==== ========================================

240
mozilla/webtools/bugzilla/docs/en/rst/api/core/v1/field.rst Normal file
View File

@ -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.
========== ====== =============================================================

373
mozilla/webtools/bugzilla/docs/en/rst/api/core/v1/flagtype.rst Normal file
View File

@ -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'.

255
mozilla/webtools/bugzilla/docs/en/rst/api/core/v1/general.rst Normal file
View File

@ -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.
========= =====================================================================

278
mozilla/webtools/bugzilla/docs/en/rst/api/core/v1/group.rst Normal file
View File

@ -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.
============= ======= =========================================================

18
mozilla/webtools/bugzilla/docs/en/rst/api/core/v1/index.rst Normal file
View File

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

416
mozilla/webtools/bugzilla/docs/en/rst/api/core/v1/product.rst Normal file
View File

@ -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.

380
mozilla/webtools/bugzilla/docs/en/rst/api/core/v1/user.rst Normal file
View File

@ -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.

3
mozilla/webtools/bugzilla/docs/en/rst/extensions.rst
View File

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

1
mozilla/webtools/bugzilla/docs/en/rst/index.rst
View File

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

4
mozilla/webtools/bugzilla/docs/en/rst/installation.rst
View File

@ -748,8 +748,8 @@ Without this directive, Apache will not follow symbolic links
to places outside its own directory structure, and you will be to places outside its own directory structure, and you will be
unable to run Bugzilla. 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 For security reasons it is recommended to prevent Apache from logging
query strings. query strings.

50
mozilla/webtools/bugzilla/docs/makedocs.pl
View File

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

4
mozilla/webtools/bugzilla/extensions/Example/docs/en/rst/api/v1/index.rst Normal file
View File

@ -0,0 +1,4 @@
Example API v1
==============
Here is where you place your API docs for the Example extension.

1
mozilla/webtools/bugzilla/extensions/Example/doc/example.rst → mozilla/webtools/bugzilla/extensions/Example/docs/en/rst/example.rst
View File

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