The Ultimate Manual to Bitbucket API

Bitbucket is a popular Git-based code management solution for commercial use and individual developers alike. This source code repository hosting service makes it easy for developers to collaborate, plan projects, run tests, and deploy code.

But to do anything meaningful with Bitbucket, you need to understand the Bitbucket API and how it works.

What is Bitbucket API Anyway?

Before we cover Bitbucket API in greater detail, I want to make sure you understand the basic concepts of APIs.

API is short for “application program interface.” Simply put, an API allows developers to access different web tools and other information stored in the cloud. APIs are the bridge between cross-platform applications.

For example, let’s say you’re using an app on your smartphone. That app uses an internet connection to communicate with servers. The servers will interpret the data and send it back to your smartphone in a format that’s readable on your device. An API handles this communication.

Let’s look at a quick analogy to explain how APIs work.

You step into an elevator. The doors close behind you, and you select a floor number by pushing the corresponding button. From here, the elevator takes control with its own internal system. The elevator decides whether you’re going straight to the floor you selected or whether you need to stop along the way to pick up another person.

The elevator itself is an enclosed system. You’re not interested in what’s happening behind the scenes to make it work. You just need to get from one floor to another. The only way for you to communicate with the elevator is through an API—or in this case, the floor buttons.

In this analogy, the API lets you communicate with an elevator. Without it, there’d be no way for you to tell a machine what to do. The buttons with the floor numbers are the readable format.

Now let’s take this concept one step further, with a real-world example of APIs for development.

Have you ever booked a hotel online? Usually, you’ve got two choices. You can either go directly to a hotel’s website (Hyatt, Hilton, Marriott, etc.) or go to a third-party site like Hotels.com or Priceline.

If you’re on the hotel’s website, you simply select your check-in date, check-out date, and room type. The hotel checks its database behind the scenes and shows you available rooms with corresponding rates for your stay. It’s very straightforward.

But now let’s say you’re using Hotels.com to book a room. How can this third-party platform aggregate the room availability for your desired travel dates with information from dozens of hotels? The answer is simple—APIs.

Hotels.com uses APIs to connect with Hyatt, Hilton, Marriott, and other hotels. The site takes the information you put into the application, requests those dates from different hotel servers, then sends the information back to your screen so you can compare rooms.

The Bitbucket API offers the same advantages. It allows developers to access tools in the Bitbucket Cloud and other resources to connect with an application.

How Bitbucket API Works

In short, the Bitbucket API lets developers interact with Bitbucket. It can handle tasks like:

Create a new pull request
Update existing pull requests
Merge or decline pull requests
Query team memberships
Query list repositories
Query followers
List followers, user profiles, and which users follow other users
Harness commits resources
Execute create/read/update/delete (CRUD) actions

The list goes on and on.

Bitbucket APIs work by providing a standard interface that interacts with the Bitbucket server and other applications. Whether you’re building desktop apps, mobile apps, browser extensions, plugins, integrations, or anything else, you can use Bitbucket APIs to facilitate communication across platforms.

There are actually several different Bitbucket APIs that you can take advantage of. It all depends on your specific use cases and what you’re trying to accomplish. We’ll take a closer look at each of these APIs and examples below:

Example 1: Bitbucket REST APIs

Bitbucket REST APIs give developers access to data entities and resources through URL paths. To use one of these APIs, your app needs to make an HTTP request and parse the reply. Since the Bitbucket REST APIs operate through HTTP, it’s easy to use these APIs with any framework or programming language.

The Bitbucket Server REST API is divided into different modules. Each module is provided through its own bundled plugin. Here’s a quick overview of those modules:

Core REST API — The Core API offers REST resources for core functions like repositories, user management, pull requests, projects, and server administration.
Audit REST API — This API provides developers with resources to query subsets of audit events that are stored against projects and repositories. The full audit logs will only be available in the audit log files.
Branch REST API — You can use this API to manage branch models and repository branches with REST resources.
Code Insights REST API — The Builds API provides resources needed to update build info and query build info.
Code Insights REST API — The Code Insights API lets developers create reports and annotate pull requests.
Comment Likes REST API — Includes REST resources to add, remove, and query comment likes.
Default Reviewers REST API — Offers REST resources to manage default reviewer configs in a repository.
Git REST API — This remote API supports different git-specific functions in Bitbucket from the Java API. It allows you to manage repository tags as well.
Personal Access Tokens REST API — Use this API to create, delete, and retrieve access tokens. It also supports the modification of existing token permissions and names.
Jira REST API — The Jira API supports querying Jira issues that are indexed against various commits.
GPG key REST API — Includes REST resources to accommodate different GPC key operations.
Ref Restriction REST API — Manage repository ref restrictions with REST resources using the Ref Restriction REST API.
Repository Ref Synchronization REST API — Manage and sync refs in a repository in Bitbucket.
Rolling Upgrades REST API — If you upgrade to a Bitbucket cluster through this API, you can manage the process for rolling upgrades.
SSH REST API — The SSH API lets you manage SSH keys for users with REST resources.

The REST API modules are some of the most popular APIs used in Bitbucket. As you can see, they can be extremely versatile for varying use cases.

Example 2: Bitbucket Server Java API

The Server Java API is also divided into different modules. Each module supports a wide array of services and classes that can be used with plugins.

With every Bitbucket server release, each module gets published as a different Maven artifact. The version number of the module matches the release number for the Bitbucket server.

Java APIs include:

Bitbucket Server API
Branches
Builds
Code Insights
Comment Likes
Git
Jira Integration
Ref Restrictions
SCM Common
SSH Support
Web Common

To import any of these in Maven, you must add the corresponding dependency to your pom.xml file. Here are some examples of what these dependencies look like for Jira Integration, SSH Support, and SCM Common:

Rather than re-creating each dependency on your own, you can simply navigate to this Bitbucket resource and copy them directly.

Example 3: Javascript API

The Javascript API can be used to build the UI for a plugin or application with Bitbucket.

The API’s compatibility policy matches other APIs in Bitbucket. It won’t break between minor versions, such as 3.1 and 3.2. Any methods or properties that have been removed or modified will create a warning in the console when it’s being used. Legacy behaviors won’t work after major releases.

It’s also worth noting that the Javascript API’s availability isn’t guaranteed. Before you use it, you need to depend on all matching web resources for that particular module. Each Javascript module has a web resource key, which will be listed in your module.

The stability of the Javascript API is only guaranteed in browsers that Bitbucket supports for each release. The list of supported browsers might change even from one minor version to another.

Bitbucket’s Javascript API is fairly complex and should only be used by experienced developers. With that said, It’s really useful for the following patterns:

Immediately-invoked function expressions (IIFE)
Promises
Events and AMD

If you’re using the Javascript API to define your own modules, be very careful with what you name them. Make sure to include a prefix that defines the module. Otherwise, you could have conflicts with existing plugins. For example, don’t start a module name with something like “internal/” or “atlassian/” or “bitbucket/”. These are all reserved for Bitbucket core.

Instead, you format your module names like “yourcompany/your-module” or “yourcompany/your-second-module”.

How to Get Started With Bitbucket API

Now that you understand what the Bitbucket API is and how it works, it’s time to get started using it on your own.

As mentioned earlier, there are lots of different APIs and use cases within Bitbucket. But regardless of what you’re trying to accomplish, you can follow these steps to build some momentum and get familiar with using the API. Then you can replicate this process for your intended use cases.

The steps below assume that you’re already up and running in Bitbucket. If you’re not, make sure you sign up and create an account. Otherwise, you won’t be able to proceed.

Step 1: Generate an Authorization Token

First, you need to generate an app password that will be used for credentialing. This will access your repositories from your code.

Navigate to your Bitbucket account and find your profile on the left side of your screen. Then click your personal settings menu.

Next, select Create app password within the App passwords menu.

Bitbucket will prompt you to enter different permissions. You’ll have the option to select permissions like read, write, read and write, edit, delete, admin, and more for the following sections:

Account
Workspace membership
Projects
Repositories
Pull requests
Issues
Wikis
Snippets
Pipelines
Webhooks

Make sure you give your app password a name, then click the Create button to proceed.

Step 2: Retrieve File Contents With a GET Request

To send a REST API request, you’ll need to establish a connection to the Bitbucket Cloud API.

Once you establish a connection to your Bitbucket repos, you can use a GET function to retrieve the file from your master branch. Look for the existing file. This will retrieve the contents of that particular file and save it to your connectionDataStream.

Step 3: Create a New Feature Branch

It’s typically in your best interest to create a new feature branch whenever changes are added and committed. You can also do this whenever you create a new pull request for approval.

Your goal here is to create a branch from the sourceBranch to the featureBranch.

You can use a Java function here to establish a connection from the Bitbucket repository. Then just send a POST request to create a new feature branch from your “source –> feature.”

Step 4: Create a File and Commit the Changes

Next, you can use another Java function to create or modify a file within your Bitbucket repository. If it’s a new file, it will automatically get created in the repository.

Make sure that the data you’re using here is in a string format. This ensures that your function fills with data that matches your corresponding parameters.

Step 5: Create a New Pull Request From the Feature Branch to Master

Once the file has been created, any modifications in the feature branch will be merged to the master.

This is accomplished with a pull request from the destination to the source. In this case, the source is prToBranch, and the destination is prFromBranch. You may need to verify that the destination feature branch currently exists. If not, add it in.

Now you’ve officially used the Bitbucket REST API in Java to connect two resources in Bitbucket. These steps are easily repeatable for any similar API function.