olsh / sharpbucket

SharpBucket is a .Net wrapper for the Bitbucket's REST API.

SharpBucket

SharpBucket is a .Net wrapper for the Bitbucket Cloud's REST APIs. It is written in in C#. With it you can have all the data of your repositories / issues at your fingertips.

How to get started

Installation

To install SharpBucket, run the following command in the Package Manager Console:

PM> Install-Package SharpBucket

Usage

See the SharpBucketCli Project or the unit tests to see how to use the wrapper.

Here's just a brief demo:

First let's set your entry point to the API:

// your main entry to the Bitbucket API, this one is for V2
var sharpBucket = new SharpBucketV2();
// authenticate with OAuth2 keys
sharpBucket.OAuth2ClientCredentials(consumerKey, consumerSecretKey);

There are various end points you can use. Let's look at the users end point:

// getting the users end point (accountName can be the name of a user or a team)
var userEndPoint = sharpBucket.UsersEndPoint("accountName");
// querying the Bitbucket API for various info
var userProfile = userEndPoint.GetProfile();
var user = userEndPoint.GetUser();
var followers = user.ListFollowers();
var follows = user.ListFollowing();
var userRepos = user.ListRepositories();

Sub end points are named Resource but are very similar to root end points. Let's look at the repository resource:

// getting the repositories end point
var repositoriesEndPoint = sharpBucket.RepositoriesEndPoint();
// getting the Repository resource for a specific repository
var repositoryResource = repositoriesEndPoint.RepositoryResource("accountName", "repoSlugOrName");
// getting the list of all the commits of the repository
var commits = repositoryResource.ListCommits();

Sending information is just as easy:

var newRepository = new Repository
                    {
                        name = "Sample",
                        language = "c#",
                        scm = "git"
                    };
var newRepositoryResult = repositoryResource.PostRepository(newRepository);

Pagination is handled internally, and we always return an aggregation of all pages by default. However you can provide few parameters to manage that behavior

// you can give us a maximum number of results to fetch on all list method
var followers = user.ListRepositories(50);

// And on some advanced list methods you can provide a ListParameters object
// that allow to inject filter and sort parameters
// see Atlassian documentation for the filter and sort syntax:
// https://developer.atlassian.com/bitbucket/api/2/reference/meta/filtering
var listParameters = new ListParameters { Filter = "name ~ \"erik/\"", Sort = "-name", Max = 50 };
var erikBranchesDesc = repositoryResource.BranchesResource.ListBranches(listParameters);

// we also provide few helpers to build your filters in FilterBuilder class:
FilterBuilder.ParseSingleQuotedString("name ~ 'erik/'"); // return "name ~ \"erik/\""
FilterBuilder.FormatDateTime(DateTime.UtcNow); // return something like "2000-12-31T23:59:59.999z"

SharpBucket uses a strict naming convention:

• methods starting with List will return a collection of items (ListIssues() returns a list of issues)
• methods starting with Enumerate will return a lazy enumeration of items (EnumerateSearchCodeSearchResults() returns a lazy page by page enumeration of SearchCodeSearchResults)
• methods starting with Get will return an item (GetIssue(10) will return an issue with the id 10)
• methods starting with Post are used for adding the item
• methods starting with Put are used for updating the item
• methods starting with Delete will delete the item

Authentication

There are three ways you can authenticate with SharpBucket:

• via Oauth 2, which is preferred
• via Oauth 1.0a
• via Bitbucket username and password

Here is how you can use them:

Basic authentication

// authenticate with Bitbucket username and password
sharpBucket.BasicAuthentication(email, password);

OAuth 1.0 authentication

With OAuth you can choose between 2 legged and 3 legged authentication.

Two legged is as simple as basic authentication:

// authenticate with OAuth keys
sharpBucket.OAuth1TwoLeggedAuthentication(consumerKey, consumerSecretKey);

The three legged requires an additional step to retrieve the pin / verifier from Bitbucket. If you do not supply a callback url (or use “oob”) you will be provided with a Bitbucket url that you can use to prompt your user to allow access to your application and retrieve a pin / verifier.

Here is a simple example of how you could use the pin / verifier retrieved from the browser:

var authenticator = sharpBucket.OAuth1ThreeLeggedAuthentication(consumerKey, consumerSecretKey, "oob");
var uri = authenticator.StartAuthentication();
Process.Start(uri);
var pin = Console.ReadLine();
// we can now do the final step by using the pin to get our access tokens
authenticator.AuthenticateWithPin(pin);

If you have a server able to receive Bitbucket's response, you would simply use your server's url as the callback and then wait for Bitbucket to send you the pin to that address.

If you already have tokens (those returned by AuthenticateWithPin method) you can simply skip the authentication process:

var authenticator = sharpBucket.OAuth1ThreeLeggedAuthentication(consumerKey, consumerSecretKey, oauthToken, oauthTokenSecret);

OAuth2 authentication

OAuth 2.0 offers a large choice of scenarios (bitbucket OAuth 2.0) but they are not yet all implemented.

Client credentials Grant is similar to OAuth1 two legged authentication:

// authenticate with OAuth keys
sharpBucket.OAuth2ClientCredentials(consumerKey, consumerSecretKey);

How much of the API is covered?

SharpBucket does not yet supply complete coverage of the API. However, the main functionality is covered and the remainder of the API should become covered sooner or later.

Contributing

Contributions are always welcome! Here is some short information about how and where to get started.

Continuous Integration from AppVeyor

The project is using AppVeyor's Continuous Integration Service which is free for open source projects. It is enabled for Pull Requests as well as the main branch.

Licensing, Dependencies and Influence

SharpBucket is licensed under MIT license.

Dependencies

• RestSharp for HTTP requests and responses. RestSharp is licensed under Apache 2.0 license terms.

Influence

SharpBucket was influenced by ServiceStack's Stripe api wrapper. The first versions of SharpBucket used ServiceStack's library, but has since moved to RestSharp.