bitbucket-rest

java client, based on jclouds, to interact with Bitbucket's REST API.

Setup and How to use

Client's can be built like so:

  BitbucketClient client = BitbucketClient.builder()
  .endPoint("http://127.0.0.1:7990") // Optional. Defaults to http://127.0.0.1:7990
  .credentials("admin:password") // Optional.
  .build();

  Version version = client.api().systemApi().version();

Being built on top of jclouds means things are broken up into Apis. Apis are just Interfaces that are analagous to a resource provided by the server-side program (e.g. /api/branches, /api/pullrequest, /api/commits, etc..). The methods within these Interfaces are analagous to an endpoint provided by these resources (e.g. GET /api/branches/my-branch, GET /api/pullrequest/123, DELETE /api/commits/456, etc..). The user only needs to be concerned with which Api they need and then calling its various methods. These methods, much like any java library, return domain objects (e.g. POJO's) modeled after the json returned by bitbucket.

Interacting with the remote service becomes transparent and allows developers to focus on getting things done rather than the internals of the API itself, or how to build a client, or how to parse the json.

On new features

New Api's or endpoints are generally added as needed and/or requested. If there is something you want to see just open an ISSUE and ask or send in a PullRequest. However, putting together a PullRequest for a new feature is generally the faster route to go as it's much easier to review a PullRequest than to create one ourselves. There is no problem doing so of course but if you need something done now than a PullRequest is your best bet otherwise you may have to patiently wait for one of our contributors to take up the work.

Latest release

Can be sourced from jcenter like so:

<dependency>
  <groupId>com.cdancy</groupId>
  <artifactId>bitbucket-rest</artifactId>
  <version>X.Y.Z</version>
  <classifier>sources|tests|javadoc|all</classifier> (Optional)
</dependency>

Documentation

javadocs can be found via github pages here

Property based setup

Client's do NOT need supply the endPoint or credentials as part of instantiating the BitbucketClient object. Instead one can supply them through system properties, environment variables, or a combination of the 2. System properties will be searched first and if not found we will attempt to query the environment.

Setting the endpoint can be done with any of the following (searched in order):

bitbucket.rest.endpoint
bitbucketRestEndpoint
BITBUCKET_REST_ENDPOINT

Setting the credentials can be done with any of the following (searched in order):

bitbucket.rest.credentials
bitbucketRestCredentials
BITBUCKET_REST_CREDENTIALS

Credentials

bitbucket-rest credentials can take 1 of 2 forms:

Colon delimited username and password: admin:password
Base64 encoded username and password: YWRtaW46cGFzc3dvcmQ=

Understanding Error objects

When something pops server-side bitbucket will hand us back a list of Error objects. Instead of failing and/or throwing an exception at runtime we attach this List of Error objects to most domain objects. Thus, it is up to the user to check the handed back domain object to see if the attached List is empty, and if not, iterate over the Error objects to see if it's something truly warranting an exception. List of Error objects itself will always be non-null but in most cases empty (unless something has failed).

An example on how one might proceed:

PullRequest pullRequest = client.api().pullRequestApi().get("MY-PROJECT", "MY-REPO", 99999);
if (pullRequest.errors().size() > 0) {
    for(Error error : pullRequest.errors()) {
        if (error.message().matches(".*Pull request \\d+ does not exist in .*")) {
            throw new RuntimeException(error.message());
        }
    }
}

Examples

The mock and live tests provide many examples that you can use in your own code.

Components

jclouds - used as the backend for communicating with Bitbucket's REST API
AutoValue - used to create immutable value types both to and from the bitbucket program

Testing

Running mock tests can be done like so:

./gradlew mockTest

Running integration tests can be done like so (requires Bitbucket instance):

./gradlew integTest

bokc / bitbucket-rest