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

Aug 7, 2024 • 6 minute read

Introduction

Hey there, fellow dev! Ready to dive into the world of BitBucket API integration? You're in for a treat. We'll be using the nifty bitbucket package to make our lives easier. Let's get cracking!

Prerequisites

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

Node.js and npm installed (but you knew that already, right?)
A BitBucket account and API credentials (if you don't have these, go grab 'em real quick)

Setting up the project

Let's kick things off:

mkdir bitbucket-api-project
cd bitbucket-api-project
npm init -y
npm install bitbucket

Easy peasy, lemon squeezy!

Authentication

Time to get cozy with the BitBucket API:

const { Bitbucket } = require('bitbucket');

const bitbucket = new Bitbucket({
  auth: {
    username: 'YOUR_USERNAME',
    password: 'YOUR_APP_PASSWORD'
  }
});

Pro tip: Use environment variables for those credentials. Safety first!

Basic API operations

Let's flex those API muscles:

// Fetch repo info
const { data } = await bitbucket.repositories.get({ workspace: 'YOUR_WORKSPACE', repo_slug: 'YOUR_REPO' });

// List branches
const { data: branches } = await bitbucket.refs.listBranches({ workspace: 'YOUR_WORKSPACE', repo_slug: 'YOUR_REPO' });

// Get commit details
const { data: commit } = await bitbucket.commits.get({ workspace: 'YOUR_WORKSPACE', repo_slug: 'YOUR_REPO', commit: 'COMMIT_HASH' });

Working with Pull Requests

PRs are where the magic happens:

// Create a PR
const { data: newPR } = await bitbucket.pullrequests.create({
  workspace: 'YOUR_WORKSPACE',
  repo_slug: 'YOUR_REPO',
  _body: {
    title: 'My awesome feature',
    source: { branch: { name: 'feature-branch' } },
    destination: { branch: { name: 'main' } }
  }
});

// List open PRs
const { data: openPRs } = await bitbucket.pullrequests.list({ workspace: 'YOUR_WORKSPACE', repo_slug: 'YOUR_REPO' });

// Approve a PR
await bitbucket.pullrequests.approve({ pullrequest_id: PR_ID, workspace: 'YOUR_WORKSPACE', repo_slug: 'YOUR_REPO' });

Managing repository content

Let's play with some files:

// Fetch file contents
const { data } = await bitbucket.source.read({ workspace: 'YOUR_WORKSPACE', repo_slug: 'YOUR_REPO', path: 'path/to/file' });

// Create or update a file
await bitbucket.source.createOrUpdate({
  workspace: 'YOUR_WORKSPACE',
  repo_slug: 'YOUR_REPO',
  path: 'path/to/file',
  _body: {
    message: 'Update file',
    branch: 'main',
    contents: Buffer.from('New content').toString('base64')
  }
});

// Delete a file
await bitbucket.source.delete({
  workspace: 'YOUR_WORKSPACE',
  repo_slug: 'YOUR_REPO',
  path: 'path/to/file',
  _body: {
    message: 'Delete file',
    branch: 'main'
  }
});

Webhooks

Keep your ear to the ground:

// Set up a webhook
await bitbucket.webhooks.create({
  workspace: 'YOUR_WORKSPACE',
  repo_slug: 'YOUR_REPO',
  _body: {
    description: 'My webhook',
    url: 'https://your-webhook-url.com',
    active: true,
    events: ['repo:push', 'pullrequest:created']
  }
});

// In your webhook handler
app.post('/webhook', (req, res) => {
  const event = req.headers['x-event-key'];
  const payload = req.body;
  // Handle the event
  res.sendStatus(200);
});

Error handling and best practices

Don't let errors catch you off guard:

try {
  // Your API calls here
} catch (error) {
  console.error('Oops!', error);
}

And remember, respect those rate limits. Nobody likes a spammer!

Conclusion

And there you have it! You're now armed and dangerous with BitBucket API knowledge. Go forth and integrate!

Resources

Happy coding, you magnificent developer, you!