User:Gerv/BugzillaAPIDesign

Note: This now exists - this document is only of historical interest.

This is a design scratchpad for an HTTP RESTful API for Bugzilla. It will be implemented as a proxy, using a variety of methods (the existing API, web scraping) on the back end and with a clean interface as defined here on the front end.

Authentication: currently, it requires the username and password on every request. This is OK as long as we support HTTPS. Later, perhaps we can enhance with Basic auth later (or simply cookies?). If you don't log in, you get public information only.

"Unconditionally" means that a particular call does not check to see if the bug has been updated since a particular time. The idea is that there is one call (bug/<id> PUT) where you can set any field, and that call always checks, but there are some situations (e.g. adding comments, adding/removing CCs) where it's useful to have a call where you don't need to do error handling and conflict resolution.

There are three different possible implementation avenues for each API call:

• The Bugzilla XML-RPC API
• The Perl "BZ::Client" module, which is a front end to parts of the XML-RPC API
• Calling the Bugzilla .cgi files directly, perhaps using a template to get output as something friendlier than HTML.

Bugs

The <id> parameter must be a bug number for now; aliases may be added later.

/bug GET

• Return list of bugs
• Takes all the same parameters as query.cgi, except that some field names are cleaned up (as in the current web services interface)
• Takes field ('column') control parameters
• Can take a parameter to return just a count of bugs
• Implementation: direct calling of the web interface, retrieve results as CSV and reformat. This is because none of the other methods gives as much flexibility.

/bug POST

• Add new bug
• Allows the setting of all fields; if there are some that the standard interface doesn't allow, we do a second bug edit submission under the covers.

Implementation: XML-RPC API and direct process_bug submission.

/bug/<id> GET

• Return single bug data
• Includes flags, CC list, related bugs and attachment metadata
• Can take parameters to add attachment data, comments and history
• Implementation: Directly request bug as XML and reformat.

/bug/<id> PUT

• Update bug
• Can change any fields
• Always checks for conflicts and returns an error if there are any
• Implementation: direct process_bug.cgi submission.

Conflict resolution will need to be implemented by the client; 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 the client will need to GET again, resolve the conflicts with the user using a UI of their choice, and attempt another PUT.

/bug/<id>/attachment GET

• Return list of all attachments on a bug
• Implementation: from bug XML.

/bug/<id>/attachment POST

• Add new attachment
• Unconditional - no conflict checking
• Implementation: direct attachment.cgi submission.

/attachment/<id> GET

• Return attachment
• Just metadata by default; can take a param to return the file data too
• Metadata includes size so client can decide whether it wants the data
• Implementation: from bug XML.

/attachment/<id> PUT

• Update attachment metadata
• Conflict checking
• Implementation: direct attachment.cgi submission.

/bug/<id>/comment GET

• Return list of comments
• Can take a "new_since" parameter to return only recent ones
• Implementation: XML-RPC API.

/bug/<id>/comment POST

• Append comment
• Unconditional - no conflict checking
• Implementation: XML-RPC API.

/bug/<id>/comment/<id> GET

• Return a single comment
• XXX Do we need this?
• Does the DB reference comments by number? If not, can we count?
• Implementation: from bug XML.

/bug/<id>/history GET

• Return bug history data
• XXX Do we need a new_since parameter?
• Implementation: XML-RPC API.

/bug/<id>/flag GET

• return list of valid flags and their state
• Implementation: direct Web UI manipulation?

/bug/<id>/flag PUT

• Update flag states - send entire representation of flags
• Conflict checking
• Implementation: direct Web UI manipulation?

/bug/<id>/cc GET

• Return list of people CCed
• Implementation: from bug XML.

/bug/<id>/cc POST

• Update person or persons (add/remove)
• Unconditional - no conflict checking; if person to remove is already gone, or person to be added is already there, just does nothing with that person.
• Implementation: posting to process_bug.cgi.

/bug/<id>/related GET

• Return the two lists of dependencies (blocking/blocked), and related bugs
• Implementation: from bug XML.

/bug/<id>/related POST

• update one or more of those lists (add/remove)
• Unconditional - no conflict checking; if bug to remove is already gone, or bug to be added is already there, just does nothing with that bug.
• Implementation: posting to process_bug.cgi.

Bugzilla

/config GET

• returns a load of info about Bugzilla's configuration, inc. version and timezone
• Implementation: parsing config.cgi? Or XML-RPC API.

/values/<field_name> GET

• Returns list of legal values for a given field
• Can take product parameter for product-specific fields, marked with a *
• Field names: product, component*, target_milestone*, version*, keyword, platform, op_sys, priority, severity, any multi-valued custom field.
• XXX What about searchable/enterable products?
• Implementation: XML-RPC API directly (although BZ::Client does products)

Users

/user GET

• returns list of users
• Query on ID, name or both; must be fast to support suggestions
• Implementation: XML-RPC API directly.

/user/<id> GET

• returns info about individual user
• 'id' can be user number or email address
• Implementation: XML-RPC API directly.

To Do

• Mass change?