Bugzilla:REST API: Difference between revisions
(Updated warning to recommend native REST) |
No edit summary |
||
| Line 8: | Line 8: | ||
== Summary == | == Summary == | ||
Bugzilla 5.0 has a native REST API, an HTTP version of its XMLRPC and JSONRPC APIs. It is [http:// | Bugzilla 5.0 has a native REST API, an HTTP version of its XMLRPC and JSONRPC APIs. It is [http://bmo.readthedocs.org/en/latest/api/index.html documented] along with the other WebServices and Bugzilla's internal interfaces. '''This is the preferred way to interface with Bugzilla from external apps''', web or otherwise. | ||
This native REST API has been backported to [[BMO]] and is available for use there. On BMO, the previous REST API, [[Bugzilla:BzAPI|BzAPI]], is considered '''DEPRECATED'''. There exists a [[Bugzilla:BzAPI:CompatLayer|compatibility layer]] to help transition away from the BzAPI server. | This native REST API has been backported to [[BMO]] and is available for use there. On BMO, the previous REST API, [[Bugzilla:BzAPI|BzAPI]], is considered '''DEPRECATED'''. There exists a [[Bugzilla:BzAPI:CompatLayer|compatibility layer]] to help transition away from the BzAPI server. | ||
| Line 22: | Line 22: | ||
== Documentation == | == Documentation == | ||
The REST API is [http:// | The REST API is [http://bmo.readthedocs.org/en/latest/api/ documented] along with the other WebServices and Bugzilla's internal interfaces. '''[Note that the API documentation was completely rewritten in late 2014 to be much more readable]''' | ||
=== Examples of native REST API use === | === Examples of native REST API use === | ||
Latest revision as of 16:19, 12 April 2023
This page documents the new native REST API available since Bugzilla 5.0 and currently available on bugzilla.mozilla.org. This is the currently recommended solution for integrating Bugzilla with third-party applications.
BzAPI is an alternate, deprecated REST API that can be used with older Bugzilla installations (although upgrading to the latest Bugzilla version is always recommended). This is separate server software that interfaces with Bugzilla and provides a similar interface to the new native REST API. BzAPI supports Bugzilla versions 3.4 and higher. BzAPI's documentation used to live here but has moved.
Bugzilla's REST API
Summary
Bugzilla 5.0 has a native REST API, an HTTP version of its XMLRPC and JSONRPC APIs. It is documented along with the other WebServices and Bugzilla's internal interfaces. This is the preferred way to interface with Bugzilla from external apps, web or otherwise.
This native REST API has been backported to BMO and is available for use there. On BMO, the previous REST API, BzAPI, is considered DEPRECATED. There exists a compatibility layer to help transition away from the BzAPI server.
Background
Until recently, Bugzilla supported only older technologies, namely XMLRPC and JSONRPC. The BMO team created a new REST API in the summer of 2013 to provide a modern Web interface to Bugzilla.
Prior to the native REST API, a separate proxy service called BzAPI was created that provided a REST API using data obtained through the older RPC interfaces as well as various other Bugzilla data sources, including CSV representations. See the docs on the BzAPI-compatibility layer for more info.
There has been discussion in bug 866927 about making small changes to the current upstream API that bring it closer to the format used by the BzAPI proxy. We will create individual bugs as needed for any changes that are to be made. We also plan on versioning the different API changes so that users can still continue to use an older format rather than breaking their client code.
Documentation
The REST API is documented along with the other WebServices and Bugzilla's internal interfaces. [Note that the API documentation was completely rewritten in late 2014 to be much more readable]
Examples of native REST API use
public data
Here are few examples of using the API (without logging in, so with public data)
Get all data for a single bug
However you almost always never need all data. Use "include_fields" to request just the data you need. Most of the calls to Bugzilla support "include_fields".
Get all comments for a single bug
Get history of all metadata changes for a single bug
Get data for all the bugs in the 29 Branch
Get data for all the bugs assigned to a particular user
Get data for all the bugs with the keyword "topcrash"
Get all the bugs that are mentored
Get data about a particular product
Get data about products and components
Get data for a user
with authentication
First you need to call a /login with login=username&password=password (Docs)
# Python example, you get a token back that you can use for future calls
>>> r = requests.get('https://bugzilla.mozilla.org/rest/login?login=username&password=password')
>>> r
<Response [200]>
>>> r.text
u'{"id":272475,"token":"272345-L1KydUNCwq"}'
# Use this token to get authenticated search results # e.g. to pull all the tracked bugs for FF31 >>> url = 'https://bugzilla.mozilla.org/rest/bug' # specify which fields you want so it's faster >>> u = url + "?token=272345-L1KydUNCwq&f1=cf_tracking_firefox31&o1=equals&v1=%2B&include_fields=id" >>> search_results = requests.get(u) >>> search_results.text u'{"bugs":[{"id":639524},{"id":798158},{"id":821809}]}'
with two factor authentication
If you have two factor authentication on your Bugzilla account (which is recommended), then you will not be able to call the login endpoint. Instead create a new API key. Then that API key can be passed to each request. For example in Python:
>>> r = requests.get('https://bugzilla.mozilla.org/rest/bug', params={'id': '1214433', 'api_key': 'the-api-key-from-the-bugzilla-userprefs-page'})
>>> print res.json()['bugs'][0]['id']
1214433