API 2.0: New function and enhanced usability

By on November 12, 2013

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:

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 APIThe 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

api20

For details of the specific APIs, visit our documentation or try an API interactively in the REST browser.

  • Друнк Мен

    Cool news! Waiting for this a lot. Going to spend night on new API investigation. Thanks a lot!

  • http://coffee-coding.com/ Thomas Sattlecker

    very nice improvement!

  • Друнк Мен

    So long time and only a few features added to the new API. I really don’t understand why the API numbered as 2.0. Perhaps API developers thinking that everything is OK with the API 1.0. I’m pretty sure they are wrong. I was hopping to see more cool features or even fully redesigned API. I was hopping to be able to get the issue title or issue id from events instead of some kind of strange ID. I was hoping to be able to assign issue to person from allowed people list. I was hopping to get a diff info with people face. But… It seems two years a API dev team just worked on some pull request features and … called that API number 2.

  • anton

    Guys, your docs about API are very worth and has a lot of typos. Bitbucket API is really complicated. You add team features, but just for read mode.

  • http://www.versioneye.com/ Robert Reiz

    We used the new BitBucket API 2.0 for the Integration with VersionEye. It worked so far quiet well. Fetching repositories, branches and project files works via API 2.0. But for the “Login with BitBucket” we had to use API 1.0. Now we are using 2 different versions of the BitBucket API at VersionEye. Would be nice if ALL endpoints are available via version 2.0 ;-)

    Here is a blog post about our BitBucket integration: http://blog.versioneye.com/2014/01/02/versioneye-bitbucket/