Today Bitbucket Cloud is proud to announce an update to its V2 API, designed to offer developers a more robust and consistent usage experience when building Bitbucket Cloud integrations. And while we’ve improved the API and its documentation to make for a smoother integration experience, we’re most excited for you to try the changes we’ve made to Bitbucket Connect and the API Proxy. It’s now easier than ever to build efficient and performant apps for Bitbucket Cloud.
Build with greater coverage, consistency, and control
We heard from many of you that consistency was lacking with version 1.0 of Bitbucket Cloud’s API, and we’ve set about focusing on a more consistent experience with this update. And with more exciting changes to come, you can expect more thoughtful design and uniformity moving forward.
With that in mind, here are the biggest changes to Bitbucket Cloud’s V2 API.
Filtering results with BBQL and partial responses
Bitbucket Query Language (BBQL) is a generic querying language you can use to filter results from Bitbucket. With BBQL you can configure your Bitbucket integrations to only request and handle the data that matters to them. Different but related is the ability to query for partial responses, since this lets you be explicit about what fields you do or don’t want included in the response. These methods for filtering the response data aren’t just useful for trimming down the data returned to your application, they actually improve the time taken to process the request in Bitbucket thanks to lazy evaluation of the data being returned.
See it in action
In the following example we’re querying for issues with a title like “timeouts” and where the issue priority is at least “major”, and we’re asking for exactly the title, state and assignee username to be returned in the response. The q query parameter indicates some BBQL that we want to include, and the fields query parameter indicates that we want to use partial responses to choose what fields are returned.
In the next example, we use BBQL to query for pull requests that were created after the 1st of February 2018, and we use the additive partial responses operator to request that the reviewers are also returned in the response (by default they are omitted).
If you are familiar with GraphQL, you’ll find that the combination of BBQL and partial responses brings a lot of that power and flexibility to plain REST endpoints.
Better dev docs, for the win
Good APIs are nothing without good documentation, so we spent time addressing the gaps and inconsistencies we found in our developer documentation with this update. Our new API documentation is built on top of the Open API Specification 2.0 (formerly Swagger), and as an Open API member organization, we built and released the RADAR doc generator tool for rendering documentation written according to this specification. Our updated documentation is designed to offer a more thorough and understandable overview of what endpoints are available and how they work.
Like everything we build at Atlassian, we depend on feedback from our integrations partners. So peruse through our doc and give us some feedback in the Atlassian Developer Community. Tell us, what’s working? What’s missing? Where can we do better?
New APIs recently released
We recently rolled out some new additions to the V2 API to help you write amazing integrations. Check out the fancy new documentation for:
- querying user and team permissions
- updating issues and querying issue updates
- creating forks
- commit history of a file
- querying ssh keys
- a new and improved diffstat API
- updating issue comments
- creating and deleting branches
- creating and deleting tags
- commit comments
Bitbucket Connect and the API proxy, a game-changer
Last but certainly not least, we have Bitbucket Connect. For those unaware, a great way to develop integrations for Bitbucket Cloud is to use the Atlassian Connect framework. Integrations built using Atlassian Connect can do things like query the Bitbucket Cloud APIs on behalf of users, and also add content to the UI to customize the look and feel of apps built for Bitbucket.
Another great benefit of apps built with Connect is the ability for apps to add their own endpoints to the Bitbucket Cloud API. Requests to such resources are proxied via Bitbucket Cloud and then sent on to the application for handling. Doing this comes with a host of benefits, including:
- a feel that the application is part of Bitbucket Cloud
- objects can be hydrated by the API proxy on the way to the application, which greatly reduces the need for applications to replicate data from Bitbucket Cloud in their own data stores, and this is important for applications that are trying to reduce the amount of sensitive data they are storing about users in a post-GDPR world
- user authentication is handled by Bitbucket Cloud, which allows for simpler logic in the application
- transparent permission checks can be used to apply authorization at the proxy before requests are forwarded to the application
This is our most exciting change with our new API improvements. Why? Because the proxy module aims to provide a much tighter and simpler integration experience for applications. We’re excited to see what you build with it, and encourage you to leave some feedback in the Atlassian Developer Community to tell us how you’re using it, and how it can be improved in future iterations.
