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.
To install SharpBucket, run the following command in the Package Manager Console:
PM> Install-Package SharpBucket
See the SharpBucketCli Project or the unit tests to see how to use the wrapper.
Here's just a brief demo:
First lets 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. Lets take a look at Users end point:
// getting the User 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 followers = user.ListFollowers();
var follows = user.ListFollowing();
var userRepos = user.ListRepositories();Sub end points are named Resource but are pretty similar. Lets 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
There are three ways you can authenticate with SharpBucket
- via Oauth 2, which is preferred
- via Oauth 1.0a
- via Bitbucket's username and password
Here is how you can use them:
// authenticate with username and password
sharpBucket.BasicAuthentication(email, password);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 one requires an additional step for getting the pin / verifier from the Bitbucket. If you do not supply a callback url (or use "oob") you will get a Bitbucket's url that will promt your user to allow access for your application and supply you with the pin / verifier. Here is a simple example of how you could manually copy paste the pin 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 had a server waiting from 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 the tokens (those returned by AuthenticateWithPin method) you can simply skip the authentication process:
var authenticator = sharpBucket.OAuth1ThreeLeggedAuthentication(consumerKey, consumerSecretKey, oauthToken, oauthTokenSecret);OAuth 2.0 offer 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);While a complete coverage of the API is preferred SharpBucket currently does not support everything yet. But the main functionality is covered and the rest should also get covered sooner or later.
Contributions are always welcome! Here is some short information about how and where to get started.
The project is using AppVeyor's Continuous Integration Service that is free for open source projects. It is enabled for Pull Requests as well as the main branch.
SharpBucket is licensed under MIT license.
- RestSharp for HTTP requests and responses. RestSHarp is licensed under Apache 2.0 license terms.
SharpBucket was influenced by ServiceStack's Stripe api wrapper. The first versions of SharpBucket used ServiceStack's library, but has since moved to RestSharp.