keqingyuan/bitbucket-rest

Java client, built on top of jclouds, for working with Bitbucket's REST API

bitbucket-rest

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

On jclouds, apis and endpoints

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/bintray like so:

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

Maven repository Configuration:

• Download a sample settings.xml file that has configured profile to pull from the correct maven repository using this link: settings.xml

OR

• Add the following repository to the project pom.xml file under project tag:

    <repositories>
      <repository>
        <snapshots>
          <enabled>false</enabled>
        </snapshots>
        <id>jcenter</id>
        <name>bintray</name>
        <url>http://jcenter.bintray.com</url>
      </repository>
    </repositories>

Documentation

javadocs can be found via github pages here

Examples on how to build a BitbucketClient

When using Basic (e.g. username and password) authentication:

BitbucketClient client = BitbucketClient.builder()
.endPoint("http://127.0.0.1:7990") // Optional and can be sourced from system/env. Falls back to http://127.0.0.1:7990
.credentials("admin:password") // Optional and can be sourced from system/env and can be Base64 encoded.
.build();

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

When using Bearer (e.g. token) authentication:

BitbucketClient client = BitbucketClient.builder()
.endPoint("http://127.0.0.1:7990") // Optional and can be sourced from system/env. Falls back to http://127.0.0.1:7990
.token("123456789abcdef") // Optional and can be sourced from system/env.
.build();

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

When using Anonymous authentication or sourcing from system/environment (as described below):

BitbucketClient client = BitbucketClient.builder()
.endPoint("http://127.0.0.1:7990") // Optional and can be sourced from system/env. Falls back to http://127.0.0.1:7990
.build();

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

On System Property and Environment Variable setup

Client's do NOT need to supply the endPoint or authentication 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 Variables. If neither turns up anything than anonymous access is assumed.

Setting the endpoint can be done like so (searched in order):

`System.setProperty("bitbucket.rest.endpoint", "http://my-bitbucket-instance:12345")`
`export BITBUCKET_REST_ENDPOINT=http://my-bitbucket-instance:12345`

Setting the credentials, which represents Basic authentication and is optionally Base64 encoded, can be done like so (searched in order):

`System.setProperty("bitbucket.rest.credentials", "username:password")`
`export BITBUCKET_REST_CREDENTIALS=username:password`

Setting the token, which represents Bearer authentication, can be done like so (searched in order):

`System.setProperty("bitbucket.rest.token", "abcdefg1234567")`
`export BITBUCKET_REST_TOKEN=abcdefg1234567`

On Overrides

Because we are built on top of jclouds we can take advantage of overriding various internal HTTP properties by passing in a Properties object or, and in following with the spirit of this library, configuring them through System Properties of Environment Variables. The properties a given client can configure can be found HERE.

When configuring through a Properties object you must pass in the keys exactly as they are named within jclouds:

Properties props = new Properties();
props.setProperty("jclouds.so-timeout", "60000");
props.setProperty("jclouds.connection-timeout", "120000");

BitbucketClient client = BitbucketClient.builder()
.overrides(props)
.build();

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

When configuring through System Properties you must prepend the jclouds name with bitbucket.rest.:

System.setProperty("bitbucket.rest.jclouds.so-timeout", "60000");
System.setProperty("bitbucket.rest.jclouds.connection-timeout", "120000");

BitbucketClient client = BitbucketClient.builder()
.build();

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

When configuring through Environment Variables you must CAPITALIZE all characters, replace any . with _, and prepend the jclouds name with BITBUCKET_REST_:

export BITBUCKET_REST_JCLOUDS_SO-TIMEOUT=60000
export BITBUCKET_REST_JCLOUDS_CONNECTION-TIMEOUT=120000

BitbucketClient client = BitbucketClient.builder()
.build();

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

It should be noted that when using this feature a merge happens behind the scenes between all possible ways one can pass in overrides. Meaning if you pass in a Properties object, and there are System Properties and Environment Variables set, then all 3 will be merged into a single Properties object which in turn will be passed along to jclouds. When it comes to precedence passed in Properties take precedence over System Properties which in turn take precedence over Environment Variables.

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. If there are any questions feel free to open an issue and ask.

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

Various properties exist for you to configure how the integTest task can be run should the defaults not suffice. These properties can be overridden by specifying -Pproperty=value on the commandline. For example, to override the integTest credentials, ./gradlew -PtestBitbucketRestCredentials=user:pass integTest.

Additional Resources

• Bitbucket docker setup
• Bitbucket REST API
• Bitbucket Auth API
• Apache jclouds