Today, Bitbucket officially launches our 2.0 REST APIs. This release supplies new functionality you can use to automate teams, repositories, branch restrictions, and manage pull requests. In this release you’ll get the ability to:
- Post new or update existing pull requests
- Manage pull request activity by merging or declining pull requests
- Query team membership, list repositories, and followers, as well as who a team is following
- List user profiles, followers, and who a user follows
- Harness the commits resource in a manner similar to Git and Mercurial’s built-in log commands
- Execute full CRUD (create/read/update/delete) actions on a repository’s branch restrictions
We are especially proud of the 2.0 API’s usability. Our API offering has grown over the years while we raced to deliver you a feature-rich API. The 2.0 API is optimized for RESTfulness, discoverability, consistency, performance, and flexibility.
Discoverable resources through links
Every 2.0 endpoint contains a links element that points to related resources. Links give a caller the ability to quickly discover and traverse related objects. We think you’ll find an object’s links perform a “self-documenting” function for every endpoint.
$ curl https://api.bitbucket.org/2.0/users/evzijst
{
"username": "evzijst",
"website": "",
"display_name": "Erik van Zijst",
"type": "user",
"links": {
"self": {
"href": "https://api.bitbucket.org/api/2.0/users/evzijst"
},
"repositories": {
"href": "https://api.bitbucket.org/api/2.0/users/evzijst/repositories"
},
"html": {
"href": "https://bitbucket.org/evzijst"
},
"followers": {
"href": "https://api.bitbucket.org/api/2.0/users/evzijst/followers"
},
"avatar": {
"href": "http://www.gravatar.com/avatar/d41d8cd98f00b204e9998ecf8427e?d=&s=32"
},
"following": {
"href": "https://api.bitbucket.org/api/2.0/users/evzijst/following"
}
},
"created_on": "2010-12-02T18:32:03+00:00",
"location": ""
}
Links can be actual REST API resources, or they can be informative. In this example, informative resources include the user’s avatar, and the HTML URL for the user’s Bitbucket account.
Paginated responses
Many endpoints return collections of objects. To avoid overwhelming clients with excessively large responses, the 2.0 API breaks these returns into manageable pages wrapped in a well-defined structure:
$ https://api.bitbucket.org/2.0/repositories/atlassian?page=2
{
"next": "https://api.bitbucket.org/2.0/repositories/atlassian?page=3",
"values": [],
"pagelen": 10,
"size": 265,
"page": 2,
"previous": "https://api.bitbucket.org/2.0/repositories/atlassian?page=1"
}
The next and previous links ensure you don’t have to hard code or manually construct any links. Paginated responses always contain a values list and next link (except for the last page of course). All other elements are optional, depending on the underlying data set (backwards navigation is not always supported).
Standardized error responses
For when things don’t work out so well, we’ve standardized the error response layout. The 2.0 API serves a new JSON object along with the appropriate HTTP status code. The JSON object provides a detailed problem description:
{
"error": {
"message": "Bad request",
"fields": {
"src": [
"This field is required."
]
},
"detail": "You must specify a valid source branch when creating a pull request.",
"id": "4545180c2f36d7cdbea3c6c3c22c52e1c3a40fd9"
}
}
Standard ISO-8601 timestamps
Oh, and while we were at it, we made it so the 2.0 API uses standardized ISO-8601 timestamps. This standardization should eliminate the need for custom date parsing patterns.
Interactive REST browser
For details of the specific APIs, visit our documentation or try an API interactively in the REST browser.