Ruby
Need help with bitbucket?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.
bitbucket-rest-api

Description

BitBucket API gem - bitbucket_rest_api

132 Stars 161 Forks MIT License 258 Commits 29 Opened issues

Services available

Need anything else?

BitBucketAPI

Gem Version

Wiki | RDocs

A Ruby wrapper for the BitBucket REST API.

Installation

Install the gem by issuing

gem install bitbucket_rest_api

or put it in your Gemfile and run

bundle install
gem "bitbucket_rest_api"

Usage

Create a new client instance

bitbucket = BitBucket.new

At this stage you can also supply various configuration parameters, such as

:user
,
:repo
,
:oauth_token
,
:oauth_secret
,
:basic_auth
which are used throughout the API. These can be passed directly as hash options:
bitbucket = BitBucket.new oauth_token: 'request_token', oauth_secret: 'request_secret'

Alternatively, you can configure the BitBucket settings by passing a block:

bitbucket = BitBucket.new do |config|
  config.oauth_token   = 'request_token'
  config.oauth_secret  = 'request_secret'
  config.client_id     = 'consumer_key'
  config.client_secret = 'consumer_secret'
  config.adapter       = :net_http
end

You can authenticate either using OAuth authentication or through basic authentication by passing your login and password credentials

bitbucket = BitBucket.new login:'vongrippen', password:'...'

or use convenience method:

bitbucket = BitBucket.new basic_auth: 'login:password'

You can interact with BitBucket interface, for example repositories, by issuing following calls that correspond directly to the BitBucket API hierarchy

bitbucket.repos.changesets.all  'user-name', 'repo-name'
bitbucket.repos.keys.list     'user-name', 'repo-name'

The response is of type [Hashie::Mash] and allows to traverse all the json response attributes like method calls.

Inputs

Some API methods apart from required parameters such as username or repository name allow you to switch the way the data is returned to you, for instance by passing a block you can iterate over the list of repositories

bitbucket.repos.list do |repo|
    puts repo.slug
end

Advanced Configuration

The

bitbucket_rest_api
gem will use the default middleware stack which is exposed by calling
stack
on client instance. However, this stack can be freely modified with methods such as
insert
,
insert_after
,
delete
and
swap
. For instance to add your
CustomMiddleware
do
bitbucket = BitBucket.new do |config|
  config.stack.insert_after BitBucket::Response::Helpers, CustomMiddleware
end

Furthermore, you can build your entire custom stack and specify other connection options such as

adapter
bitbucket = BitBucket.new do |config|
  config.adapter :excon

config.stack do |builder| builder.use BitBucket::Response::Helpers builder.use BitBucket::Response::Jsonize end end

API

Main API methods are grouped into the following classes that can be instantiated on their own

BitBucket         - full API access

BitBucket::Repos BitBucket::Issues

Some parts of BitBucket API require you to be authenticated, for instance the following are examples of APIs only for the authenticated user

BitBucket::Issues::Create

You can find out supported methods by calling

actions
on a class instance in your
irb
:
>> BitBucket::Repos.actions                 >> bitbucket.issues.actions
---                                         ---
|--> all                                    |--> all
|--> branches                               |--> comments
|--> collaborators                          |--> create
|--> commits                                |--> edit
|--> contribs                               |--> events
|--> contributors                           |--> find
|--> create                                 |--> get
|--> downloads                              |--> labels
|--> edit                                   |--> list
|--> find                                   |--> list_repo
|--> forks                                  |--> list_repository
|--> get                                    |--> milestones
|--> hooks                                  ...
...

Configuration

Certain methods require authentication. To get your BitBucket OAuth credentials, register an app with BitBucket.

BitBucket.configure do |config|
  config.oauth_token   = YOUR_OAUTH_REQUEST_TOKEN          # Different for each user
  config.oauth_secret  = YOUR_OAUTH_REQUEST_TOKEN_SECRET   # Different for each user
  config.client_id     = YOUR_OAUTH_CONSUMER_TOKEN
  config.client_secret = YOUR_OAUTH_CONSUMER_TOKEN_SECRET
  config.basic_auth    = 'login:password'
end

or

BitBucket.new(:oauth_token => YOUR_OAUTH_REQUEST_TOKEN, :oauth_secret => YOUR_OAUTH_REQUEST_TOKEN_SECRET) BitBucket.new(:basic_auth => 'login:password')

Development

Questions or problems? Please post them on the issue tracker. You can contribute changes by forking the project and submitting a pull request. You can ensure the tests are passing by running

bundle
and
rake
.

Copyright

Copyright (c) 2012 James M Cochran. Original github_api gem Copyright (c) 2011-2012 Piotr Murach. See LICENSE.txt for further details.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.