![Stack Overflow](https://img.shields.io/badge/stack%20overflow-bitbucket%E2%80%93rest-4183C4.svg)
bitbucket-rest
![alt tag](https://wac-cdn.atlassian.com/dam/jcr:e2a6f06f-b3d5-4002-aed3-73539c56a2eb/bitbucket_rgb_blue.png?cdnVersion=cm)
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 maven like so:
<dependency>
<groupId>io.github.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