Bugzilla:BzAPI

From MozillaWiki
Revision as of 19:03, 10 December 2009 by Gerv (talk | contribs) (→‎Servers)
Jump to navigation Jump to search

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:

Versions

Older pages in this wiki document released versions of BzAPI.

Version 0.1 (4th October 2009)

Version 0.2 (11th November 2009)

Version 0.3 (24th November 2009)

Servers

Installations of the API are available pointed at two Bugzilla servers - the main Mozilla one and the testing server. You can also use a specific version of the API, or just "the latest stable version".

Main Mozilla server (https://bugzilla.mozilla.org/): 

https://api-dev.bugzilla.mozilla.org/0.3/
https://api-dev.bugzilla.mozilla.org/latest/

Staging server (https://bugzilla-stage-tip.mozilla.org/): 

https://api-dev.bugzilla.mozilla.org/stage/0.3/
https://api-dev.bugzilla.mozilla.org/stage/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 (stable) edge, use URLs with "latest" in.

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.

Authentication

The API and the proxy support anonymous access as much as the target Bugzilla does. If you want to authenticate, pass: 

username=fred@bedrock.com&password=ilovewilma

as query parameters on any request. The above-mentioned instance of the API is available over HTTPS and accesses bugzilla.mozilla.org over HTTPS.

The cert on the API machine is signed by the Mozilla Root CA. Its MD5 fingerprint is 75:B2:EF:89:81:51:8F:99:13:DC:BF:44:47:0E:A9:8D.

Data Formats

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.

Currently, the API has only been tested with JSON (MIME type: "application/json"). However, Catalyst::Controller::REST supports a number of serialization and deserialization formats, and can be extended for more. Feel free to set "Accept: application/xml" and see what you get back, and then try feeding it back in again. But be aware that the XML output format, and any other non-JSON formats for that matter, are very much not frozen.

Errors

All of the "output" documentation below documents successful returns :-) Calls may also return an Error.

The documentation below gives a list of possible values for the "message" field; the list is almost certainly not exhaustive. Error handling is always a large part of any good API, and is one place where this one might be a little rough. In the future, ponies will provide each possible error object with a single unambiguous error code in a "code" field. The other codes are not guaranteed to be present, or continue to be present if they are there now. 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.

Conflicts

There are two calls (bug/<id> PUT and attachment/<id> PUT) where you can set any field on that bug or attachment. If you pass a last_change_time, these calls will check for editing conflicts. If you do not, they will unconditionally update the bug to the state you send.

If there is a conflict, conflict resolution must be implemented by the client. So if you call /bug/<id> PUT and the bug changed since your GET (i.e. the web interface would mid-air), you'll get an error, and your client will need to GET again, resolve the conflicts with the user using a UI of your choice, and attempt another PUT.

API Calls

List of API calls, with input and output details and possible errors.

Please note the following:

  • All times are supplied as UTC, in the ISO 8601 extended format (e.g. "2009-06-21T12:34:56Z"). This should define the time unambiguously, and should be widely and easily parseable, at the expense of probably not being directly displayable without a little manipulation.
  • Votes are not supported.
  • Examples are in JSON format because I had to pick one; see above regarding other formats.

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 release of Bugzilla (many features will not work on 3.2); and
  • to be using UTF-8 (this is the default on new installations).

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 me tips from your experience.

You can get the code from the Mozilla Mercurial (hg) repository: 

hg co http://hg.mozilla.org/webtools/bzapi bzapi

Patches

Even on top of the latest stable release of Bugzilla 3.4, you will need to apply a few further patches. (Unfortunately, it was not possible to support all the necessary functionality without some changes to Bugzilla itself, which were considered either unnecessary or too intrusive for a stable release series.)

Retrieved from "https://wiki.mozilla.org/index.php?title=Bugzilla:BzAPI&oldid=188675"