java client, based on jclouds, to interact with Bitbucket's REST API.
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.
Can be sourced from jcenter like so:
<dependency>
<groupId>com.cdancy</groupId>
<artifactId>bitbucket-rest</artifactId>
<version>0.9.0</version>
<classifier>sources|tests|javadoc|all</classifier> (Optional)
</dependency>
javadocs can be found via github pages here
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.endpointbitbucketRestEndpointBITBUCKET_REST_ENDPOINT
Setting the credentials can be done with any of the following (searched in order):
bitbucket.rest.credentialsbitbucketRestCredentialsBITBUCKET_REST_CREDENTIALS
bitbucket-rest credentials can take 1 of 2 forms:
- Colon delimited username and password: admin:password
- Base64 encoded username and password: YWRtaW46cGFzc3dvcmQ=
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());
}
}
}
The mock and live tests provide many examples that you can use in your own code.
- 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
Running mock tests can be done like so:
./gradlew mockTest
Running integration tests can be done like so (requires Bitbucket instance):
./gradlew integTest