Step by Step Guide to Building a BitBucket API Integration in Ruby

Aug 7, 2024 • 5 minute read

Introduction

Hey there, fellow dev! Ready to supercharge your workflow with BitBucket's API? Let's dive into building a slick integration using the tinybucket gem. This guide will have you up and running in no time, so buckle up!

Prerequisites

Before we jump in, make sure you've got:

A Ruby environment (you're a pro, so I'm sure you've got this covered)
A BitBucket account with API credentials (if not, hop over to BitBucket and set that up real quick)

Installation

First things first, let's get tinybucket installed:

gem install tinybucket

Easy peasy, right?

Authentication

Now, let's get you authenticated:

require 'tinybucket'

Tinybucket.configure do |config|
  config.oauth_token = 'YOUR_OAUTH_TOKEN'
  config.oauth_secret = 'YOUR_OAUTH_SECRET'
end

client = Tinybucket.new

Replace those placeholders with your actual credentials, and you're good to go!

Basic Operations

Let's start with some basic operations to get your feet wet:

Fetching repositories

repos = client.repos
repos.each do |repo|
  puts repo.full_name
end

Accessing user information

user = client.user('username')
puts user.display_name

Listing pull requests

repo = client.repo('owner', 'repo_slug')
pull_requests = repo.pull_requests
pull_requests.each do |pr|
  puts "#{pr.title} - #{pr.state}"
end

Advanced Operations

Ready to level up? Let's tackle some more complex operations:

Creating and updating issues

repo = client.repo('owner', 'repo_slug')
new_issue = repo.issues.create({ title: 'New Feature', content: 'Let\'s add this awesome feature!' })
new_issue.update({ state: 'resolved' })

Managing webhooks

repo = client.repo('owner', 'repo_slug')
webhook = repo.hooks.create({
  description: 'My awesome webhook',
  url: 'https://example.com/webhook',
  active: true,
  events: ['repo:push', 'issue:created']
})

Working with branches and commits

repo = client.repo('owner', 'repo_slug')
branch = repo.branches.find('master')
commits = branch.commits
commits.each do |commit|
  puts "#{commit.hash} - #{commit.message}"
end

Error Handling

Don't let those pesky errors catch you off guard:

begin
  repo = client.repo('owner', 'non_existent_repo')
rescue Tinybucket::Error::NotFound => e
  puts "Oops! Repo not found: #{e.message}"
rescue Tinybucket::Error::Unauthorized => e
  puts "Hold up! You're not authorized: #{e.message}"
end

Best Practices

Keep an eye on those rate limits! BitBucket's not too strict, but it's always good to be mindful.
Cache responses when you can. Your future self will thank you when you're handling larger datasets.

Testing

Don't forget to test your integration! Here's a quick example using RSpec and WebMock:

require 'webmock/rspec'

RSpec.describe 'BitBucket API Integration' do
  it 'fetches repositories' do
    stub_request(:get, /api.bitbucket.org\/2.0\/repositories/)
      .to_return(status: 200, body: '{"values": [{"full_name": "test/repo"}]}')

    repos = client.repos
    expect(repos.first.full_name).to eq('test/repo')
  end
end

Conclusion

And there you have it! You're now equipped to build some seriously cool integrations with BitBucket's API. Remember, the tinybucket documentation is your best friend for diving deeper.

Now go forth and code something awesome! 🚀