Bugzilla:BzAPI

From MozillaWiki
Revision as of 16:45, 24 November 2009 by Gerv (talk | contribs) (→‎Conflicts)
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.

There is a page where you can add tips, tricks and code samples.

Versions

Older pages in this wiki document released versions of BzAPI.

Version 0.1 (4th October 2009)

Version 0.2 (11th November 2009)

Servers

The existing implementation of the API is a proxy which can be installed and pointed at any Bugzilla (version 3.4 or above for full capabilities). An installation of the latest version, pointed at https://bugzilla.mozilla.org/, can be found at: 

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

There is a test Bugzilla server at https://bugzilla-stage-tip.mozilla.org/. There is a version of the API pointed at this server, which should be used for testing API clients: 

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

As the API is tweaked and revised, the version number in these URLs will increase, so updates don't break every single client immediately. However, old versions are not guaranteed to persist. Authors of API-using tools are strongly encouraged to join the mozilla.tools mailing list to be kept up to date.

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 Notes

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

API Calls: Bugs

Search for bugs (/bug GET)

Input

A) Search parameters, exactly as powerful as query.cgi but using the field names from the Bug object rather than those from the web interface. (At the moment, it does also support the field names from the web interface, to make it easy to port URLs and other code across. But if supporting this becomes difficult, it might go away.)

B) As above, with parameter count=1.

Output

A) 

{ "bugs": [ <array of Bug> ] }

B) Count of bugs: 

{ "count": 136 }

Notes

  • Only a subset of a bug's fields are returned on a search. These are those in bold on the list. As a rule of thumb, only single-valued fields are returned.

Errors

Create new bug (/bug POST)

Input

Bug as POST body.

Output

201 Created status code, Location header pointing to new bug object. 

{ "ref": "<same-as-location-header>" }

Notes

  • You can't add attachments with a new bug. Any attachment fields in the bug object will be ignored. Make a separate call.

Errors

Retrieve bug (/bug/<id> GET)

Input

  • Bug ID on the URL
  • Includes flags, CC list, related bugs and attachment metadata by default
  • Does not include attachment data, comments or history - so amount of data is bounded
  • attachmentdata=1, comments=1 and history=1 do the obvious things (history requires 3.4)
  • Multi-valued custom fields are not, in general, returned as arrays if there is 0 or 1 value. This is because I can't tell which custom fields are supposed to be multi-valued. As a hack, if your custom field name begins "cf_multi", it will get unconditionally array-ified. This limitation can only be lifted when the API is part of Bugzilla itself.

Output

Bug.

Notes

  • If you want to retrieve multiple Bugs at once, use the Search interface and specify only Bug IDs as your search criteria. You will be returned full Bug objects instead of the reduced number of fields normally presented on a Search. This is a shortcut to avoid people having to make 20 calls to get 20 full bug objects.

Errors

Update bug (/bug/<id> PUT)

Input

Bug as PUT body.

Output 

{ "ok": 1 }

Notes

  • You can only add one comment per call. Add a Comment object without an id to the comments array.
  • This call does not support the updating of attachment metadata. Make a separate call to update attachments.
  • Set assigned_to or qa_contact to the special value null (in JSON) to reset them to the default for the current component.
  • To make this call check for conflicts, submit the last_change_time you received when getting the bug data. To make unconditional updates (be careful!) simply do not supply a last_change_time.
  • You can update most fields singly, but some fields are coupled, and must be provided as a set (even if one has not changed), as follows:
    • 'status' and 'resolution'
    • 'blocks' and 'dependson'
    • 'component' and 'product'
    • 'version' and 'target_milestone' require 'product'

Errors

  • This call will return a "Mid-air collision" error if you submit a last_change_time earlier than the one Bugzilla has on record.

List comments for bug (/bug/<id>/comment GET)

Input

  • Bug ID on the URL
  • "new_since" DateTime parameter (YYYYMMDDTHHMMSS format only) returns only ones since date given. (3.4 or above only)

Output 

{ "comments": [ array of Comment ] }

In other words, a Bug with only the comment field.

Notes

  • No comments (or none you can see) -> empty array.

Notes

Errors

Add new comment to bug (/bug/<id>/comment POST)

Input

Comment as POST body.

Output

201 Created status code, Location header pointing to bug/<id>/comment (as individual comments don't have their own location). 

{ "ref": "<same-as-location-header>" }

Notes

  • Unconditional - no conflict checking

Errors


List history for bug (/bug/<id>/history GET)

Input

  • Bug ID on the URL.

Output 

{ "history": [ array of ChangeSet ] }

In other words, a Bug with only the history field.

Notes

  • This call requires Bugzilla 3.4 or above.

Errors

List flags for bug (/bug/<id>/flag GET)

Input

  • Bug ID on the URL.

Output 

{ "flags": [ array of Flag ] }

In other words, a Bug with only the flags field.

Notes

Errors

API Calls: Attachments

List attachments for bug (/bug/<id>/attachment GET)

Input

  • Bug ID on the URL.
  • attachmentdata=1 does the obvious thing.

Output 

{ "attachments": [ array of Attachment ] }

In other words, a Bug with only the attachment field.

Notes

  • No attachments -> empty array.

Errors

Create new attachment (/bug/<id>/attachment POST)

Input

Attachment as POST body.

Output

201 Created status code, Location header pointing to new object. 

{ "ref": "<same-as-location-header>" }

Notes

  • You can't set is_obsolete on a new attachment submission
  • You can't set the same (multi-settable) flag twice on a single attachment submission

Errors

Retrieve attachment (/attachment/<id> GET)

Input

  • Attachment ID on the URL.
  • attachmentdata=1 does the obvious thing.

Output

Attachment.

Notes

Errors

Update attachment metadata (/attachment/<id> PUT)

Input

Attachment as PUT body.

Output 

{ "ok": 1 }

Notes

  • You can't set the same (multi-settable) flag twice on a single attachment submission
  • To make this call check for conflicts, submit the last_change_time you received when getting the attachment data. To make unconditional updates (be careful!) simply do not supply a last_change_time.

Errors

API Calls: Users

Search for users (/user GET)

Input

  • "match" parameter with string to match against either name or real_name.

Output 

{ users: [ array of User ] }

Notes

  • No matches -> empty array.
  • This call requires Bugzilla 3.4 or above.

Errors

Retrieve user (/user/<id> GET)

Input

User ID on the URL. Can be numeric ID or email address.

Output

User.

Notes

  • This call requires Bugzilla 3.4 or above.

Errors

API Calls: Other

Configuration (/configuration GET)

Input

  • None

Output 

Configuration

Notes

  • flags=0 parameter removes flag-related information from the config; because flags can be enabled or disabled per-component, there is a lot of flag-related info and so this cuts down the size significantly. However, you will not be able to add new flags to bugs or attachments without this info.

Errors

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=185367"