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