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