{"id":21030687,"url":"https://github.com/cdancy/bitbucket-rest","last_synced_at":"2025-04-04T22:07:04.487Z","repository":{"id":8769865,"uuid":"59324109","full_name":"cdancy/bitbucket-rest","owner":"cdancy","description":"Java client, built on top of jclouds, for working with Bitbucket's REST API ","archived":false,"fork":false,"pushed_at":"2025-03-19T10:22:47.000Z","size":7775,"stargazers_count":78,"open_issues_count":25,"forks_count":58,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-28T21:06:55.649Z","etag":null,"topics":["api","api-client","bitbucket","bitbucket-rest","ci","cicd","client","continuous-integration","java","jclouds","rest","rest-api"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cdancy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-05-20T20:24:14.000Z","updated_at":"2025-02-12T14:43:55.000Z","dependencies_parsed_at":"2023-02-10T10:31:04.895Z","dependency_job_id":"845c985c-8c04-484a-98ef-4a4de68221cd","html_url":"https://github.com/cdancy/bitbucket-rest","commit_stats":null,"previous_names":[],"tags_count":51,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdancy%2Fbitbucket-rest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdancy%2Fbitbucket-rest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdancy%2Fbitbucket-rest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdancy%2Fbitbucket-rest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cdancy","download_url":"https://codeload.github.com/cdancy/bitbucket-rest/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247256112,"owners_count":20909240,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-client","bitbucket","bitbucket-rest","ci","cicd","client","continuous-integration","java","jclouds","rest","rest-api"],"created_at":"2024-11-19T12:19:49.500Z","updated_at":"2025-04-04T22:07:04.465Z","avatar_url":"https://github.com/cdancy.png","language":"Java","readme":"\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.github.cdancy/bitbucket-rest/badge.png)](https://maven-badges.herokuapp.com/maven-central/io.github.cdancy/bitbucket-rest)\n[![Stack Overflow](https://img.shields.io/badge/stack%20overflow-bitbucket\u0026#8211;rest-4183C4.svg)](https://stackoverflow.com/questions/tagged/bitbucket+rest)\n\n# bitbucket-rest\n![alt tag](https://wac-cdn.atlassian.com/dam/jcr:e2a6f06f-b3d5-4002-aed3-73539c56a2eb/bitbucket_rgb_blue.png?cdnVersion=cm)\n\njava client, based on jclouds, to interact with Bitbucket's REST API. \n\n## On jclouds, apis and endpoints\nBeing built on top of `jclouds` means things are broken up into [Apis](https://github.com/cdancy/bitbucket-rest/tree/master/src/main/java/com/cdancy/bitbucket/rest/features). \n`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..). \nThe 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..). \nThe 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 \n(e.g. POJO's) modeled after the json returned by `bitbucket`. \n\nInteracting with the remote service becomes transparent and allows developers to focus on getting\nthings done rather than the internals of the API itself, or how to build a client, or how to parse the json. \n\n## On new features\n\nNew Api's or endpoints are generally added as needed and/or requested. If there is something you want\nto see just open an ISSUE and ask or send in a PullRequest. However, putting together a PullRequest\nfor a new feature is generally the faster route to go as it's much easier to review a PullRequest\nthan to create one ourselves. There is no problem doing so of course but if you need something done\nnow than a PullRequest is your best bet otherwise you may have to patiently wait for one of our\ncontributors to take up the work.\n\n## Latest Release\n\nCan be sourced from maven like so:\n\n    \u003cdependency\u003e\n      \u003cgroupId\u003eio.github.cdancy\u003c/groupId\u003e\n      \u003cartifactId\u003ebitbucket-rest\u003c/artifactId\u003e\n      \u003cversion\u003eX.Y.Z\u003c/version\u003e\n      \u003cclassifier\u003esources|tests|javadoc|all\u003c/classifier\u003e (Optional)\n    \u003c/dependency\u003e\n\t\n### Maven repository Configuration:\n\n* Download a sample settings.xml file that has configured profile to pull from the correct maven repository using this link: [settings.xml](https://bintray.com/repo/downloadMavenRepoSettingsFile/downloadSettings?repoPath=%2Fbintray%2Fjcenter)\n\n**OR**\n\n* Add the following repository to the project pom.xml file under project tag:\n```\n    \u003crepositories\u003e\n      \u003crepository\u003e\n        \u003csnapshots\u003e\n          \u003cenabled\u003efalse\u003c/enabled\u003e\n        \u003c/snapshots\u003e\n        \u003cid\u003ejcenter\u003c/id\u003e\n        \u003cname\u003ebintray\u003c/name\u003e\n        \u003curl\u003ehttp://jcenter.bintray.com\u003c/url\u003e\n      \u003c/repository\u003e\n    \u003c/repositories\u003e\n```\n## Documentation\n\njavadocs can be found via [github pages here](http://cdancy.github.io/bitbucket-rest/docs/javadoc/)\n\n## Examples on how to build a _BitbucketClient_\n\nWhen using `Basic` (e.g. username and password) authentication:\n\n    BitbucketClient client = BitbucketClient.builder()\n    .endPoint(\"http://127.0.0.1:7990\") // Optional and can be sourced from system/env. Falls back to http://127.0.0.1:7990\n    .credentials(\"admin:password\") // Optional and can be sourced from system/env and can be Base64 encoded.\n    .build();\n\n    Version version = client.api().systemApi().version();\n\nWhen using `Bearer` (e.g. token) authentication:\n\n    BitbucketClient client = BitbucketClient.builder()\n    .endPoint(\"http://127.0.0.1:7990\") // Optional and can be sourced from system/env. Falls back to http://127.0.0.1:7990\n    .token(\"123456789abcdef\") // Optional and can be sourced from system/env.\n    .build();\n\n    Version version = client.api().systemApi().version();\n\nWhen using `Anonymous` authentication or sourcing from system/environment (as described below):\n\n    BitbucketClient client = BitbucketClient.builder()\n    .endPoint(\"http://127.0.0.1:7990\") // Optional and can be sourced from system/env. Falls back to http://127.0.0.1:7990\n    .build();\n\n    Version version = client.api().systemApi().version();\n\n## On `System Property` and `Environment Variable` setup\n\nClient's do NOT need to supply the endPoint or authentication as part of instantiating the\n_BitbucketClient_ object. Instead one can supply them through `System Properties`, `Environment\nVariables`, or a combination of the 2. `System Properties` will be searched first and if not\nfound we will attempt to query the `Environment Variables`. If neither turns up anything\nthan anonymous access is assumed.\n\nSetting the `endpoint` can be done like so (searched in order):\n\n    `System.setProperty(\"bitbucket.rest.endpoint\", \"http://my-bitbucket-instance:12345\")`\n    `export BITBUCKET_REST_ENDPOINT=http://my-bitbucket-instance:12345`\n\nSetting the `credentials`, which represents `Basic` authentication and is optionally Base64 encoded, can be done like so (searched in order):\n\n    `System.setProperty(\"bitbucket.rest.credentials\", \"username:password\")`\n    `export BITBUCKET_REST_CREDENTIALS=username:password`\n\nSetting the `token`, which represents `Bearer` authentication, can be done like so (searched in order):\n\n    `System.setProperty(\"bitbucket.rest.token\", \"abcdefg1234567\")`\n    `export BITBUCKET_REST_TOKEN=abcdefg1234567`\n\n## On Overrides\n\nBecause we are built on top of jclouds we can take advantage of overriding various internal _HTTP_ properties by\npassing in a `Properties` object or, and in following with the spirit of this library, configuring them\nthrough `System Properties` of `Environment Variables`. The properties a given client can configure can be\nfound [HERE](https://github.com/jclouds/jclouds/blob/master/core/src/main/java/org/jclouds/Constants.java).\n\nWhen configuring through a `Properties` object you must pass in the keys exactly as they are named within jclouds:\n\n    Properties props = new Properties();\n    props.setProperty(\"jclouds.so-timeout\", \"60000\");\n    props.setProperty(\"jclouds.connection-timeout\", \"120000\");\n\n    BitbucketClient client = BitbucketClient.builder()\n    .overrides(props)\n    .build();\n\n    Version version = client.api().systemApi().version();\n\nWhen configuring through `System Properties` you must prepend the jclouds name with `bitbucket.rest.`:\n\n    System.setProperty(\"bitbucket.rest.jclouds.so-timeout\", \"60000\");\n    System.setProperty(\"bitbucket.rest.jclouds.connection-timeout\", \"120000\");\n\n    BitbucketClient client = BitbucketClient.builder()\n    .build();\n\n    Version version = client.api().systemApi().version();\n\nWhen configuring through `Environment Variables` you must CAPITALIZE all characters,\nreplace any `.` with `_`, and prepend the jclouds name with `BITBUCKET_REST_`:\n\n    export BITBUCKET_REST_JCLOUDS_SO-TIMEOUT=60000\n    export BITBUCKET_REST_JCLOUDS_CONNECTION-TIMEOUT=120000\n\n    BitbucketClient client = BitbucketClient.builder()\n    .build();\n\n    Version version = client.api().systemApi().version();\n\nIt should be noted that when using this feature a merge happens behind the scenes between all\npossible ways one can pass in _overrides_. Meaning if you pass in a `Properties` object, and\nthere are `System Properties` and `Environment Variables` set, then all 3 will be merged into\na single `Properties` object which in turn will be passed along to _jclouds_. When it comes to \nprecedence passed in `Properties` take precedence over `System Properties` which in turn \ntake precedence over `Environment Variables`.\n\n## Understanding Error objects\n\nWhen something pops server-side `bitbucket` will hand us back a list of [Error](https://github.com/cdancy/bitbucket-rest/blob/master/src/main/java/com/cdancy/bitbucket/rest/domain/common/Error.java) objects. Instead of failing and/or throwing an exception at runtime we attach this List of `Error` objects \nto most [domain](https://github.com/cdancy/bitbucket-rest/tree/master/src/main/java/com/cdancy/bitbucket/rest/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 \ntruly warranting an exception. List of `Error` objects itself will always be non-null but in most cases empty (unless something has failed).\n\nAn example on how one might proceed:\n\n    PullRequest pullRequest = client.api().pullRequestApi().get(\"MY-PROJECT\", \"MY-REPO\", 99999);\n    if (pullRequest.errors().size() \u003e 0) {\n        for(Error error : pullRequest.errors()) {\n            if (error.message().matches(\".*Pull request \\\\d+ does not exist in .*\")) {\n                throw new RuntimeException(error.message());\n            }\n        }\n    }\n\n\n## Examples\n\nThe [mock](https://github.com/cdancy/bitbucket-rest/tree/master/src/test/java/com/cdancy/bitbucket/rest/features) and [live](https://github.com/cdancy/bitbucket-rest/tree/master/src/test/java/com/cdancy/bitbucket/rest/features) tests provide many examples\nthat you can use in your own code. If there are any questions feel free to open an issue and ask.\n\n## Components\n\n- jclouds \\- used as the backend for communicating with Bitbucket's REST API\n- AutoValue \\- used to create immutable value types both to and from the bitbucket program\n    \n## Testing\n\nRunning mock tests can be done like so:\n\n    ./gradlew mockTest\n\t\nRunning integration tests can be done like so (requires Bitbucket instance):\n\n    ./gradlew integTest\n\nVarious [properties](https://github.com/cdancy/bitbucket-rest/tree/master/gradle.properties) exist for you to configure\nhow the `integTest` task can be run should the defaults not suffice. These properties can be overridden by specifying\n`-Pproperty=value` on the commandline. For example, to override the integTest credentials, `./gradlew\n-PtestBitbucketRestCredentials=user:pass integTest`.\n\n# Additional Resources\n\n* [Bitbucket docker setup](https://bitbucket.org/atlassian/docker-atlassian-bitbucket-server)\n* [Bitbucket REST API](https://developer.atlassian.com/static/rest/bitbucket-server/latest/bitbucket-rest.html)\n* [Bitbucket Auth API](https://developer.atlassian.com/bitbucket/server/docs/latest/how-tos/example-basic-authentication.html)\n* [Apache jclouds](https://jclouds.apache.org/start/)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcdancy%2Fbitbucket-rest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcdancy%2Fbitbucket-rest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcdancy%2Fbitbucket-rest/lists"}