BitBucket API Essential Guide

What type of API does BitBucket provide?

Bitbucket primarily uses a REST API.

Key points:

1. Bitbucket offers a V2 REST API for integrating with and extending Bitbucket Cloud.

2. The V2 API provides endpoints for common Bitbucket operations like querying repositories, issues, pull requests, etc.

3. Some key features of the Bitbucket REST API include:

   • Filtering results using Bitbucket Query Language (BBQL)
   • Partial responses to request only specific fields
   • API proxy capabilities for Bitbucket Connect apps

4. Bitbucket has deprecated their older V1 API and encourages developers to migrate to the V2 REST API.

5. While Bitbucket uses REST, it's worth noting that other API styles like GraphQL and SOAP are used for different purposes in other systems.

So in summary, Bitbucket provides a REST API as its primary interface for developers to integrate with and extend the platform. The REST architecture aligns well with Bitbucket's resource-oriented model of repositories, pull requests, issues, etc.

Does the BitBucket API have webhooks?

Yes, the official BitBucket API does have webhooks, and you can subscribe to various types of events. Here's a breakdown of the key information:

Webhook Availability

BitBucket provides webhook functionality as part of its API. Webhooks allow you to configure BitBucket to make requests to your server or another external service when certain events occur.

Types of Events

You can subscribe to several types of events using BitBucket webhooks. Here are the main categories of events you can subscribe to:

1. Repository Events:

   • Push
   • Fork
   • Updated
   • Commit comment created
   • Build status created
   • Build status updated

2. Pull Request Events:

   • Created
   • Updated
   • Changes Request created
   • Change Request removed
   • Approved
   • Approval removed
   • Merged
   • Declined
   • Comment created
   • Comment updated
   • Comment deleted

3. Issue Events:

   • Created
   • Updated
   • Comment created

Key Points to Consider

• You can create webhooks both at the project and repository level.
• Webhooks created at the project level are inherited by all repositories in that project.
• You can create up to 50 webhooks per repository.
• Webhooks are triggered when the associated event occurs, and BitBucket sends a payload request to the specified URL.
• The payload includes information about the event and relevant entities (like Account, Repository, Issue, Comment, and Pull Request).

Best Practices

1. Use webhooks to integrate applications with BitBucket. For example, you can use webhooks to trigger CI/CD pipelines or display notifications in your application.

2. Ensure your webhook endpoint has a valid SSL certificate for HTTPS endpoints.

3. Consider implementing security measures like payload validation using HMAC signatures to verify that the incoming webhooks are from BitBucket.

4. Be aware of any IP address restrictions and allowlist the necessary BitBucket Cloud IP addresses if required.

In conclusion, BitBucket's webhook functionality provides a powerful way to integrate external systems with your BitBucket workflows, allowing you to automate processes and keep your systems in sync with repository activities.

Rate Limits and other limitations

Here are the key points about the API rate limits for the Bitbucket API:

Authenticated Request Limits

• Git operations (HTTPS and SSH): 60,000 requests per hour
• Raw file requests: 5,000 requests per hour
• Archive files: 5,000 files per hour
• Repository data access: 1,000 requests per hour
• Webhook data access: 1,000 requests per hour
• Application properties access: 2,000 requests per hour
• Sending invitations: 100 requests per minute

Anonymous Request Limits

• 60 requests per hour across all API resources

How the Rate Limits Work

• Rate limits are divided into one-hour rolling windows for both authenticated and unauthenticated requests.
• For every minute that passes, you get that time back to run new requests, but the total you can run consecutively over an hour is still limited.
• Once you reach the limit, you need to wait until the rolling one-hour window passes before you can make more requests.

Key Considerations

• The rate limits are subject to change and are not considered part of the API contract.
• Logging in is required to access larger request pools beyond the anonymous limit.
• There is no official documentation on the exact behavior of how the rolling window is calculated.

Best Practices

• Implement proper error handling and backoff logic in your code to handle rate limit errors gracefully.
• Consider using authentication to access higher rate limits if needed.
• Space out requests over time rather than making large bursts of requests when possible.

In summary, the Bitbucket API uses a rolling one-hour window for rate limiting, with different limits for authenticated and anonymous requests across various API resources. Proper handling of these limits is important when developing applications that interact with the Bitbucket API.

Latest API Version

Based on the search results, here are the key points regarding the most recent version of the BitBucket API:

BitBucket Cloud API

• The most recent version of the BitBucket Cloud API is 2.0 [3][4].
• BitBucket announced an update to the BitBucket Cloud 2.0 REST API, designed to offer developers a more robust and consistent experience [3].

BitBucket Server API

• BitBucket Server uses a different API than BitBucket Cloud [5].
• The BitBucket Server API does not use the same versioning system as the Cloud API. It does not have a "2.0" version [5].

Key Differences

• BitBucket Cloud and Server use different REST APIs [5].
• If you want to build a universal app that works with both BitBucket Cloud and BitBucket Server, you may need to use different API endpoints for each [5].

Best Practices

• When developing for BitBucket, it's important to check which version (Cloud or Server) you're targeting, as the APIs are different [5].
• For BitBucket Cloud, use the 2.0 REST API endpoints [3][4].
• For BitBucket Server, refer to the specific BitBucket Server REST API documentation [5].

In summary, the most recent version of the BitBucket API depends on whether you're using BitBucket Cloud or BitBucket Server. For BitBucket Cloud, the most recent version is 2.0. For BitBucket Server, there isn't a directly comparable version number, and you should refer to the specific Server API documentation.

How to get a BitBucket developer account and API Keys?

1. Create a BitBucket Account

• Go to bitbucket.org and sign up for a free account if you don't already have one.

2. Generate API Credentials

• Once logged in, go to your BitBucket settings and generate API credentials:
  • Create an App Password or Personal Access Token with the necessary permissions.
  • These will be used to authenticate your API requests.

3. Choose an Integration Method

BitBucket offers several options for integrating:

• Use the REST API directly to make calls to BitBucket.
• Build a BitBucket app using Forge (recommended for secure, scalable apps).
• Develop an Atlassian Connect app to integrate with the BitBucket UI.
• Create a pipe for BitBucket Pipelines.

4. Set Up Your Development Environment

• Install any necessary SDKs or libraries for your chosen integration method.
• Set up version control and a development workflow.

5. Implement Authentication

• Use OAuth 2.0 or Basic Auth with your API credentials to authenticate requests.
• For Forge apps, OAuth 2.0 is handled automatically.

6. Make API Calls

• Use the BitBucket REST API documentation to understand available endpoints.
• Make authenticated requests to the API to access BitBucket data and functionality.

7. Test Your Integration

• Thoroughly test your integration in a development environment.
• Ensure proper error handling and security measures are in place.

8. Deploy and Publish (if applicable)

• For public apps, you can publish to the Atlassian Marketplace.
• For private integrations, deploy securely within your organization.

What can you do with the BitBucket API?

Based on the search results provided, here is a list of data models that can be interacted with using the BitBucket API, along with what is possible for each:

Projects and Repositories

• Create, read, update, and delete projects and repositories [2][4]
• Manage repository settings and permissions [2][4]
• Access personal repositories using user-centric REST URLs [4]

Branches and Commits

• Create, list, and manage branches [3][4]
• Retrieve commit information and history [4]
• Perform operations like merging and deleting branches [3]

Pull Requests

• Create, update, and manage pull requests [2]
• Review and comment on pull requests [2]
• Merge or decline pull requests [2]

Code Insights

• Add code quality reports and annotations to pull requests [3]
• Retrieve code insight information for commits and pull requests [3]

Users and Permissions

• Manage user accounts and permissions [2][3]
• Handle authentication and access control [4]

Jira Integration

• Link Jira issues to commits and pull requests [3][5]
• Create branches from Jira issues [5]

Git Operations

• Perform Git operations like cloning, pushing, and pulling [3]
• Manage Git hooks and repository settings [3]

Comments and Code Reviews

• Add, edit, and delete comments on commits and pull requests [3]
• Manage code review processes [2]

Search

• Search for code, commits, and other resources within repositories [3]

Builds and Deployments

• Integrate with CI/CD pipelines [2][5]
• Trigger and monitor builds [5]
• Manage deployment processes [5]

SSH and GPG

• Manage SSH keys for authentication [3]
• Handle GPG signing for commits and tags [3]

Ref Restrictions and Branch Permissions

• Set up and manage branch permissions and restrictions [3]

Mirroring

• Configure and manage repository mirroring [2]

System Maintenance

• Perform system-level operations and maintenance tasks [2]

This list covers the main data models and operations available through the BitBucket API. Each of these areas provides various endpoints and methods for interacting with the corresponding data and functionality within BitBucket.