Summary

This knowledge base article will provide instructions on how to generate the reports using the Bitbucket Cloud API.

Environment

Bitbucket Cloud

Solution

Please use the following guidelines to generate the reports.

• There are various APIs available like Workspaces, Projects, Repositories, etc. Please familiarize yourself with them and understand their capabilities and available data structure to verify if they can be helpful for your requirements. Each API serves a unique requirement.

• Familiarize yourself with the following APIs, methods, and capabilities to obtain optimized and successful results

  • Authentication method - There are various authentication methods available. Use the preferred one as per your organization

  • Pagination - Pagination can be useful if the output returned by API is large and a single API call can’t return all the data

  • Filtering - You might need to get the output only for some specific values. Filtering can be useful for such cases

  • Partial response - You might want to get data for specific fields only instead of getting all of the data returned by the API

  • UUID - Bitbucket uses UUID to uniquely identify different objects. There are APIs that can require UUID as an argument

• It is possible that you might have to use more than one API to generate the report as per your requirement. How many APIs are used is completely dependent on your requirements.

Example

Requirement

Generate the list of repositories in a CSV from the workspace belonging to a specific project.

• The workspace name: workspace_rocket 
  

• The project name: project_atlas 

• Fields in the generated report: Repository name 

• Generated report CSV file name: repository_list.csv 

Implementation approach

• Here the requirement is to get the list of the repositories in a workspace hence we will use the List repositories in a workspace API

• We can use the basic authentication method (Bitbucket User name and App password)

• We will use filtering to filter only to get the repository list in workspace_rocket that belongs to only project_atlas project. query=project.key="project_atlas" 

• We will be using partial response to get only the repository name. fields=values.full_name 

• We will be using Python as a programing language to interact with the API and generate the CSV file, however, you can use any other language if you prefer, as long as it has the capabilities to perform API calls and any other processes you might need, such as, creating CSV files.

$ Curl -X GET -u <username>:<apppassword> "https://api.bitbucket.org/2.0/repositories/{workspace}?q=project.key=%22{KEY}%22&fields=values.full_name"

{
  "values": [
    {
      "full_name": "{workspace}/{repository_1}"
    },
    {
      "full_name": "{workspace}/{repository_2}"
    },
    {
      "full_name": "{workspace}/{repository_3}"
    }
  ]
}

from requests import Session
from csv import writer

username  = "" # Your Bitbucket Cloud username
password  = "" # Your App Password
workspace = "workspace_rocket" #  Your Workspace ID
project   = "project_atlas" # The Project Key

URL = f"https://api.bitbucket.org/2.0/repositories/{workspace}?q=project.key=%22{project}%22&fields=values.full_name"

session = Session()
session.auth = (username,password)

def get_repos(page=None, limit=1_000):
    while True:
        params = {'page': page, 'limit': limit}
        r = session.get(URL, params=params)
        r_json = r.json()
        for raw_repo in r_json.get('values'):
            yield raw_repo.get('full_name')

        if page == None:
            page = 1

        if r_json.get('next'):
            page += 1
        else:
            return

def main():
    # Export the data to a CSV file
    with open(f'repository_list.csv', 'x', newline='') as file:
        writer_object = writer(file)
        writer_object.writerow(['Repository Name',])
        
        for repo in get_repos():
                writer_object.writerow([repo])
    
    print("Done")


if __name__ == '__main__':
    main()

Practical tips

• If you are using multiple features like filtering and Partial response in the same API call then use the & operator.

• As a general practice, always first try to perform your API call using curl in your Terminal or any other tool, such as Postman, to make sure you are hitting the correct endpoint and fetching the data you need. Once you are satisfied with the output and it’s familiar with the fields returned, you can use it in your script.

• You might be interested in getting only specific fields from an API response. Note that all results are returned inside a list named values. Hence, to get those specific fields, you need to provide those as part of the URL endpoint:

  https://api.bitbucket.org/2.0/repositories/{workspace}?fields=values.full_name 

• Depending on where you are running the API call, some characters might need to be URL encoded, such as double quotes("). In the example provided above, the double quotes inside the URL were encoded int %22