BMO/Integration Best Practice

If you are writing tools to integrate with bugzilla.mozilla.org (BMO), you want to make sure they keep working as intended as Bugzilla changes, and that they avoid placing strain on the Bugzila infrastructure. Here are some tips and suggestions:

Guidelines

• Use the native REST API.
  • The older REST API, BzAPI, is deprecated. If you have an application currently using BzAPI, convert it to use the native API if possible; if you don't have the time/resources for that, at least switch to the native BzAPI-compatibility layer, since BzAPI will be decommissioned at some point. Switching to the native REST API will also generally result in better performance, since the BzAPI compatibility layer is a wrapper around the new API and thus each BzAPI call is more expensive than the equivalent native REST call.
• Do not poll more frequently than every 5 minutes.
  • Seriously, you don't need to poll every minute.
  • Talk with a BMO owner if you think you do, there are alternatives to polling should you require low latency updates.
• Ask for bugs updated since your last poll, or track a bug's last modified date.
  • If your system is polling for bugs, you should ask BMO for bugs updated since your last poll.
  • The chfieldfrom argument will accept times as well as dates (eg. "2012-10-08 00:00").
  • Search results generally return a bug's last-modified date; there's no need to re-request the bug if it hasn't been modified since the last time you saw it.
• Only request the fields that you are interested in.
  • By default all APIs return more information than you probably require—use the include_fields parameter to specify the exact fields you need (BzAPI, native REST and XMLRPC/JSONRPC).
  • When searching with BzAPI, avoid specifying non-bold columns if you can avoid it, because it'll be slower and user server-side resources.
• Coalesce queries where possible.
  • If you have multiple bugs, components, etc., to query, it can be more efficient issue a single request rather than iterating over your list and issuing multiple requests.
• Don't use a regular account for your bot.
  • Regular accounts may gain elevated privledges which your automation may not require (for example, all @mozilla.com accounts automatically and irrevocably have access to all employee-confidential bugs)
  • Using "https://bugzilla.mozilla.org/enter_bug.cgi?product=bugzilla.mozilla.org&component=Administration File a bug in the BMO" as property chain is not permitted during the annotation process.
    asking us to create an account for you instead (eg. mybot@ipsec.bugs).

API

Bugzilla's REST, XML-RPC, and JSON-RPC APIs have stability commitments within a major version of Bugzilla, as long as the call in question is not marked as experimental (see the API docs for the version in question). Other more ad-hoc ways of integrating, such as buglists-as-CSV and bugs-as-XML, don't have such commitments. Pick a stable API to use.

Searching

• When searching among all closed or all open bugs, don't explicitly enumerate the states, as states may be added or removed. For open bugs, you can use "resolution=---" or "bug_status=__open__" (status=__open__ for BzAPI). For closed bugs, you can use "bug_status=__closed__".
• Similarly, when searching for bugs which were not fixed, don't enumerate all of the not-fixed resolutions. Instead do a custom search using the "is not empty" operator.