Difference between revisions of "Bugzilla:BzAPI"
m |
|||
(16 intermediate revisions by 7 users not shown) | |||
Line 1: | Line 1: | ||
+ | <div style="border: thin dotted #aaa; padding:5px;"> | ||
+ | '''This specific REST API, generally referred to as "BzAPI", is DEPRECATED. For new projects, use the [[Bugzilla:REST_API|native REST API]] instead. The BMO team has implemented a [[Bugzilla:BzAPI:CompatLayer|compatibility layer]] to help existing apps transition off BzAPI onto the native REST API. Please migrate existing BzAPI-based apps to the new compatibility-layer endpoint as soon as possible, as BzAPI will be shut off at some point in the future. Direct any questions to the [[BMO]] team. | ||
+ | |||
+ | '''The native REST API is available in Bugzilla 5.0 and up, and on bugzilla.mozilla.org. Although BzAPI is deprecated, it can be used with older Bugzilla installations (versions prior to 5.0) to provide a REST API.''' | ||
+ | </div><br> | ||
+ | |||
These pages document the tip of the HTTP REST API for Bugzilla proxy software ("BzAPI"). Please file bugs (in either code or documentation) in [https://bugzilla.mozilla.org/enter_bug.cgi?product=Webtools&component=BzAPI the BzAPI component in bugzilla.mozilla.org]. | These pages document the tip of the HTTP REST API for Bugzilla proxy software ("BzAPI"). Please file bugs (in either code or documentation) in [https://bugzilla.mozilla.org/enter_bug.cgi?product=Webtools&component=BzAPI the BzAPI component in bugzilla.mozilla.org]. | ||
This page contains general information and preliminaries. Read it first. Then, you can find more detailed information: | This page contains general information and preliminaries. Read it first. Then, you can find more detailed information: | ||
− | * [https://wiki.mozilla.org/Bugzilla: | + | * [https://wiki.mozilla.org/Bugzilla:BzAPI:Methods API Methods] |
− | ** [https://wiki.mozilla.org/Bugzilla: | + | ** [https://wiki.mozilla.org/Bugzilla:BzAPI:Search Parameters for the Search method] |
− | * [https://wiki.mozilla.org/Bugzilla: | + | * [https://wiki.mozilla.org/Bugzilla:BzAPI:Objects Objects sent and received] |
− | ** [https://wiki.mozilla.org/Bugzilla: | + | ** [https://wiki.mozilla.org/Bugzilla:BzAPI:Objects:Configuration The Configuration object] |
− | * [https://wiki.mozilla.org/Bugzilla: | + | * [https://wiki.mozilla.org/Bugzilla:BzAPI:HowTo Tips, tricks and code samples] |
==Versions== | ==Versions== | ||
Line 15: | Line 21: | ||
===Version 1.3 (7th March 2013)=== | ===Version 1.3 (7th March 2013)=== | ||
− | * [https://wiki.mozilla.org/index.php?title=Bugzilla: | + | * [https://wiki.mozilla.org/index.php?title=Bugzilla:BzAPI&oldid=538111 Overview] |
− | * [https://wiki.mozilla.org/index.php?title=Bugzilla: | + | * [https://wiki.mozilla.org/index.php?title=Bugzilla:BzAPI:Methods&oldid=436589 API Methods] |
− | ** [https://wiki.mozilla.org/index.php?title=Bugzilla: | + | ** [https://wiki.mozilla.org/index.php?title=Bugzilla:BzAPI:Search&oldid=483668 Parameters for the Search method] |
− | * [https://wiki.mozilla.org/index.php?title=Bugzilla: | + | * [https://wiki.mozilla.org/index.php?title=Bugzilla:BzAPI:Objects&oldid=537941 Objects sent and received] |
− | ** [https://wiki.mozilla.org/index.php?title=Bugzilla: | + | ** [https://wiki.mozilla.org/index.php?title=Bugzilla:BzAPI:Objects:Configuration&oldid=265440 The Configuration object] |
− | * [https://wiki.mozilla.org/index.php?title=Bugzilla: | + | * [https://wiki.mozilla.org/index.php?title=Bugzilla:BzAPI:HowTo&oldid=489309 Tips, tricks and code samples] |
===Version 1.2 (21st November 2012)=== | ===Version 1.2 (21st November 2012)=== | ||
− | * [https://wiki.mozilla.org/index.php?title=Bugzilla: | + | * [https://wiki.mozilla.org/index.php?title=Bugzilla:BzAPI&oldid=358475 Overview] |
− | * [https://wiki.mozilla.org/index.php?title=Bugzilla: | + | * [https://wiki.mozilla.org/index.php?title=Bugzilla:BzAPI:Methods&oldid=436589 API Methods] |
− | ** [https://wiki.mozilla.org/index.php?title=Bugzilla: | + | ** [https://wiki.mozilla.org/index.php?title=Bugzilla:BzAPI:Search&oldid=483668 Parameters for the Search method] |
− | * [https://wiki.mozilla.org/index.php?title=Bugzilla: | + | * [https://wiki.mozilla.org/index.php?title=Bugzilla:BzAPI:Objects&oldid=292055 Objects sent and received] |
− | ** [https://wiki.mozilla.org/index.php?title=Bugzilla: | + | ** [https://wiki.mozilla.org/index.php?title=Bugzilla:BzAPI:Objects:Configuration&oldid=265440 The Configuration object] |
− | * [https://wiki.mozilla.org/index.php?title=Bugzilla: | + | * [https://wiki.mozilla.org/index.php?title=Bugzilla:BzAPI:HowTo&oldid=295460 Tips, tricks and code samples] |
==Servers== | ==Servers== | ||
Line 37: | Line 43: | ||
Main Mozilla server (https://bugzilla.mozilla.org/): | Main Mozilla server (https://bugzilla.mozilla.org/): | ||
− | [https://api-dev.bugzilla.mozilla.org/1. | + | [https://api-dev.bugzilla.mozilla.org/1.3/ https://api-dev.bugzilla.mozilla.org/1.3/] |
[https://api-dev.bugzilla.mozilla.org/latest/ https://api-dev.bugzilla.mozilla.org/latest/] | [https://api-dev.bugzilla.mozilla.org/latest/ https://api-dev.bugzilla.mozilla.org/latest/] | ||
Testing server (http://landfill.bugzilla.org/bzapi_sandbox/): | Testing server (http://landfill.bugzilla.org/bzapi_sandbox/): | ||
− | [https://api-dev.bugzilla.mozilla.org/test/1. | + | [https://api-dev.bugzilla.mozilla.org/test/1.3/ https://api-dev.bugzilla.mozilla.org/test/1.3/] |
[https://api-dev.bugzilla.mozilla.org/test/latest/ https://api-dev.bugzilla.mozilla.org/test/latest/] | [https://api-dev.bugzilla.mozilla.org/test/latest/ https://api-dev.bugzilla.mozilla.org/test/latest/] | ||
Line 95: | Line 101: | ||
== Errors == | == Errors == | ||
− | If methods are not successful for whatever reason, they will return an [[Bugzilla: | + | If methods are not successful for whatever reason, they will return an [[Bugzilla:BzAPI:Objects#Error|Error]]. ''You should test every API return to see if it is an error ("error" member set to a true value).'' |
The "code" field on an Error, if present, will give an error code from [[Bugzilla:WebServices:Errors|this list]]. The other member variables of the object are not stable, and should not be relied upon. The html_page, in particular, is only there so you can read it manually for a better idea of what the error was, and ask for the API to support it properly. | The "code" field on an Error, if present, will give an error code from [[Bugzilla:WebServices:Errors|this list]]. The other member variables of the object are not stable, and should not be relied upon. The html_page, in particular, is only there so you can read it manually for a better idea of what the error was, and ask for the API to support it properly. | ||
Line 103: | Line 109: | ||
If you want to install the API proxy on your own machine for your own Bugzilla, you will need: | If you want to install the API proxy on your own machine for your own Bugzilla, you will need: | ||
− | * the <b>latest</b> stable 3.4.x, 3.6.x, 4.0.x or 4. | + | * the <b>latest</b> stable 3.4.x, 3.6.x, 4.0.x, 4.2.x or 4.4.x point release of Bugzilla (many features will not work on 3.2); and |
* to be using UTF-8 (this is the default on new installations); and | * to be using UTF-8 (this is the default on new installations); and | ||
* to have the necessary optional modules for XML-RPC (e.g. Test::Taint); and | * to have the necessary optional modules for XML-RPC (e.g. Test::Taint); and | ||
* to apply the patches noted below. | * to apply the patches noted below. | ||
− | Then, install a copy of the API software - it does not have to be on the same machine. See the INSTALL file in the repository for some installation hints; feel free to send | + | Then, install a copy of the API software - it does not have to be on the same machine. See the INSTALL file in the repository for some installation hints; feel free to send tips from your experience to gerv@mozilla.org. |
You can get the code from the Mozilla Mercurial (hg) repository: | You can get the code from the Mozilla Mercurial (hg) repository: | ||
Line 126: | Line 132: | ||
<b>Important Note</b>: Install BZ::Client 1.03, not the latest (1.04), because BZ::Client was updated to fix some problems but the workarounds in the BzAPI code have not yet been removed. | <b>Important Note</b>: Install BZ::Client 1.03, not the latest (1.04), because BZ::Client was updated to fix some problems but the workarounds in the BzAPI code have not yet been removed. | ||
− | perl -MCPAN -e "install | + | perl -MCPAN -e "install 'JWIED/BZ-Client-1.03.tar.gz'" |
+ | |||
+ | Also, I am told that BZ-Client requires Perl 5.10.0, which is a higher requirement than that for stable Bugzilla. (Bugzilla trunk requires 5.10, but 4.4 and below only require 5.8.) | ||
===Required Extension and/or Patch(es)=== | ===Required Extension and/or Patch(es)=== | ||
Line 139: | Line 147: | ||
Secondly, if you are using non-ASCII characters at all, you need to patch the BZ::Client module, which has an encoding bug. The patch for that is also in the <tt>patches</tt> directory. | Secondly, if you are using non-ASCII characters at all, you need to patch the BZ::Client module, which has an encoding bug. The patch for that is also in the <tt>patches</tt> directory. | ||
+ | |||
+ | [[category:Bugzilla]] |
Latest revision as of 02:03, 21 September 2016
This specific REST API, generally referred to as "BzAPI", is DEPRECATED. For new projects, use the native REST API instead. The BMO team has implemented a compatibility layer to help existing apps transition off BzAPI onto the native REST API. Please migrate existing BzAPI-based apps to the new compatibility-layer endpoint as soon as possible, as BzAPI will be shut off at some point in the future. Direct any questions to the BMO team.
The native REST API is available in Bugzilla 5.0 and up, and on bugzilla.mozilla.org. Although BzAPI is deprecated, it can be used with older Bugzilla installations (versions prior to 5.0) to provide a REST API.
These pages document the tip of the HTTP REST API for Bugzilla proxy software ("BzAPI"). Please file bugs (in either code or documentation) in the BzAPI component in bugzilla.mozilla.org.
This page contains general information and preliminaries. Read it first. Then, you can find more detailed information:
Contents
Versions
Older pages in this wiki document released versions of BzAPI.
Version 1.3 (7th March 2013)
Version 1.2 (21st November 2012)
Servers
Installations of the API are available pointed at two Bugzilla servers - the main Mozilla one and the testing server. Please use the testing server for testing API clients. You can also use a specific version of the API, or just "the latest version".
Main Mozilla server (https://bugzilla.mozilla.org/):
https://api-dev.bugzilla.mozilla.org/1.3/ https://api-dev.bugzilla.mozilla.org/latest/
Testing server (http://landfill.bugzilla.org/bzapi_sandbox/):
https://api-dev.bugzilla.mozilla.org/test/1.3/ https://api-dev.bugzilla.mozilla.org/test/latest/
If you want to always use the same version, use URLs with a version number in. However, old ones are not guaranteed to persist. If you want to live on the edge, use URLs with "latest" in. However, backwardly-incompatible changes are possible at the time of a new release.
Authors of API-using tools are strongly encouraged to join the mozilla.tools mailing list to be kept up to date on changes and new releases.
Browsing the API
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 YAML-HTML, which the browser can display. In other words, you can play with the API using just your browser and see results in a human-readable form. Here is an example. This is a good way to try out the various GET calls, even if you can't use it for POST or PUT. For that, the Firefox "RESTClient" addon is very useful.
Data Formats
Aside from the above-mentioned "browsing" facility, the REST API only supports JSON input, and either JSON and 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 - add a "callback" parameter to name your callback. (Due to a bug in the Perl package Catalyst::Controller::REST, callbacks cannot contain dots.)
Authentication
The API and the proxy support anonymous access as much as the target Bugzilla does.
Note: The above-mentioned instance of the API is available over HTTPS and accesses bugzilla.mozilla.org over HTTPS. (The cert is from GeoTrust's Equifax root, which should be trusted by all current browsers.) So login information should be safe in transit.
There are two ways to authenticate.
Username and Password Auth
Pass e.g.:
username=fred@bedrock.com&password=ilovewilma
as query parameters on any request. Obviously, remember to URL encode any special characters, which are often seen in passwords.
Cookie Auth
If you have access to some existing Bugzilla login cookies for the user, you can also authenticate using that. You pass the data as URL parameters rather than as Cookie headers to prevent cross-site request forgery (XSRF).
Note that the cookies are HTTPOnly and so you can't access this info from unprivileged in-page JavaScript. However, if you have chrome privileges, you can ask the cookie service.
userid=1234&cookie=mG4J9OT4B6
The "userid" parameter is a numeric user ID, the contents of the "Bugzilla_login" cookie. The "cookie" parameter is a random string, the contents of the "Bugzilla_logincookie" cookie.
Field Control
For those calls which return significant data (i.e. GETs), each call returns a number of fields by default. Often, it's all available fields, but for some calls (e.g. bug lists, individual bugs) it's fewer than that. You can control exactly what fields you get using the include_fields and exclude_fields parameters. These take a comma-separated list of field names, and work as follows:
- If you specify some include_fields, you select just those fields
- If one of your field names is "_default" (note underscore), you select the default fields plus any others you specify
- If one of your field names is "_all" (note underscore), you select all available fields, regardless of whether you specify any others as well
- After that, if you have specified exclude_fields, they are removed before the data is returned.
Errors
If methods are not successful for whatever reason, they will return an Error. You should test every API return to see if it is an error ("error" member set to a true value).
The "code" field on an Error, if present, will give an error code from this list. The other member variables of the object are not stable, and should not be relied upon. The html_page, in particular, is only there so you can read it manually for a better idea of what the error was, and ask for the API to support it properly.
Your Own Installation
If you want to install the API proxy on your own machine for your own Bugzilla, you will need:
- the latest stable 3.4.x, 3.6.x, 4.0.x, 4.2.x or 4.4.x point release of Bugzilla (many features will not work on 3.2); and
- to be using UTF-8 (this is the default on new installations); and
- to have the necessary optional modules for XML-RPC (e.g. Test::Taint); and
- to apply the patches noted below.
Then, install a copy of the API software - it does not have to be on the same machine. See the INSTALL file in the repository for some installation hints; feel free to send tips from your experience to gerv@mozilla.org.
You can get the code from the Mozilla Mercurial (hg) repository:
hg clone http://hg.mozilla.org/webtools/bzapi bzapi
Each release is tagged in the form BZAPI_X.X_RELEASE, so feel free to pull a tag instead of the tip.
If you are installing on Ubuntu, you'll need at least the following modules (and probably many more):
sudo apt-get install libcatalyst-perl libcatalyst-modules-perl libcatalyst-action-rest-perl libtext-csv-xs-perl libarray-diff-perl libdata-walk-perl starman
and the following Perl modules via CPAN:
BZ::Client Catalyst::Plugin::Log::Handler Slurp
Important Note: Install BZ::Client 1.03, not the latest (1.04), because BZ::Client was updated to fix some problems but the workarounds in the BzAPI code have not yet been removed.
perl -MCPAN -e "install 'JWIED/BZ-Client-1.03.tar.gz'"
Also, I am told that BZ-Client requires Perl 5.10.0, which is a higher requirement than that for stable Bugzilla. (Bugzilla trunk requires 5.10, but 4.4 and below only require 5.8.)
Required Extension and/or Patch(es)
There are two changes you need to make.
Even the latest stable release of Bugzilla requires a little modification to work properly with the BzAPI. Unfortunately, it is not possible to support all the necessary functionality without some changes to Bugzilla itself, which the Bugzilla team have declined to take.
So, firstly, for Bugzilla 3.6 and above, there is a Bugzilla Extension which adds the necessary functionality. Find it in $BZAPI_HOME/extension; copy the BzAPI directory from there into $BUGZILLA_HOME/extensions.
If you are on 3.4 or below, you need a patch and a template. These are shipped in the BzAPI distribution, in the patches directory, from version 0.8 onwards. See the INSTALL file for details.
Secondly, if you are using non-ASCII characters at all, you need to patch the BZ::Client module, which has an encoding bug. The patch for that is also in the patches directory.