Bugzilla:BzAPI

From MozillaWiki
Jump to navigation Jump to search

These pages document the HTTP REST API for Bugzilla.

Servers

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

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

As the API is tweaked and revised, the version number in that URL 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 mailing list whose details will appear here very soon :-).

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

on any request. The above-mentioned instance of the API is available over HTTPS and accesses bugzilla.mozilla.org over HTTPS. Apache access logging has been disabled on the API machine.

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

Data Formats

Currently, the API has only been tested with JSON. Although it's currently the default, you should set an "Accept: application/json" header on all calls. However, Catalyst::Controller::REST supports a number of serialization and deserialization formats, and can be extended for more. XML is next on the list to test with, but set "Accept: text/xml" and see what you get back :-) And then try feeding it back in again...

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, and those calls always check for editing conflicts. All other calls which change things unconditionally make things as you request, and require no conflict resolution.

In the case of the two calls which check, 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

  • Getting bug history and details of users will only work on the above API when bugzilla.mozilla.org is upgraded to Bugzilla 3.4 :-( Features that depend on 3.4 are marked "3.4".
  • The <id> parameter for bugs must be a bug number for now; aliases will be supported later.
  • Flag support is spotty. Only those flags which are actually set, and not those which you could set, are returned. And to set a flag, you need to know the ID of the flag_type, which is not available through the API. At the moment, it's probably best to treat flags as read only.
  • Groups are not yet supported. You may get some back on the GET calls (YMMV) but setting them is unlikely to work.
  • Custom fields should work but, unlike other multi-valued fields, multi-valued ones are not 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 array-ified.
  • Only bug time fields (creation/last_change) return timezone information. For the moment, for other time fields, you will need to know the timezone of the Bugzilla you are accessing.
  • The added and removed fields of the Change object are always strings, even if the field_name is a multi-valued field and more than one value was added or removed. In that case, the values are comma-separated in the string. Parsing and auto-promotion would be possible, but has not yet been implemented.
  • Votes are not supported, and probably never will be.
  • Examples are in JSON format because I had to pick one; see above regarding other formats.

Priorities

Improving support for flags, groups and custom fields is priority #1.

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.

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.

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)

Output

Bug.

Notes

Errors

Update bug (/bug/<id> PUT)

Input

Bug as PUT body.

Output 

{ "ok": 1 }

Notes

  • You can't yet change the privacy flag on a comment

Errors

  • This call always checks for conflicts and returns an error if there is one.


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) - 3.4

Input

  • Bug ID on the URL.

Output 

{ "history": [ array of ChangeSet ] }

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

Notes

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

  • Currently only returns the flags that are actually set, rather than the flags that could be set.

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
  • XXX Conflict checking?

Errors


API Calls: Users

Search for users (/user GET) - 3.4

Input

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

Output 

{ users: [ array of User ] }

Notes

  • No matches -> empty array.

Errors


Retrieve user (/user/<id> GET) - 3.4

Input

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

Output

User.

Notes

Errors

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