{"id":23354132,"url":"https://github.com/gabrielfeo/develocity-api-kotlin","last_synced_at":"2025-04-10T06:05:30.972Z","repository":{"id":64891418,"uuid":"579131355","full_name":"gabrielfeo/develocity-api-kotlin","owner":"gabrielfeo","description":"A library to use the Develocity API in Kotlin notebooks and more","archived":false,"fork":false,"pushed_at":"2024-04-12T22:35:00.000Z","size":4659,"stargazers_count":15,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-04-13T16:33:24.054Z","etag":null,"topics":["develocity","gradle","gradle-enterprise","jupyter","jupyter-notebooks","kotlin","kotlin-notebook","kotlin-scripts","openapi-generator"],"latest_commit_sha":null,"homepage":"https://gabrielfeo.github.io/develocity-api-kotlin/","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gabrielfeo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-12-16T18:34:48.000Z","updated_at":"2024-04-14T23:51:36.336Z","dependencies_parsed_at":"2022-12-17T09:51:20.981Z","dependency_job_id":"66a5e125-7cd9-472b-af4d-c1758ee48cef","html_url":"https://github.com/gabrielfeo/develocity-api-kotlin","commit_stats":null,"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabrielfeo%2Fdevelocity-api-kotlin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabrielfeo%2Fdevelocity-api-kotlin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabrielfeo%2Fdevelocity-api-kotlin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabrielfeo%2Fdevelocity-api-kotlin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gabrielfeo","download_url":"https://codeload.github.com/gabrielfeo/develocity-api-kotlin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248166927,"owners_count":21058481,"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":["develocity","gradle","gradle-enterprise","jupyter","jupyter-notebooks","kotlin","kotlin-notebook","kotlin-scripts","openapi-generator"],"created_at":"2024-12-21T09:19:02.270Z","updated_at":"2025-04-10T06:05:30.929Z","avatar_url":"https://github.com/gabrielfeo.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Develocity API Kotlin\n\n[![Maven Central](https://img.shields.io/badge/Maven%20Central-2024.3.0-blue)][14]\n[![Javadoc](https://img.shields.io/badge/Javadoc-2024.3.0-orange)][7]\n\n(formerly `gradle-enterprise-api-kotlin`)\n\nA Kotlin library to access the [Develocity API][1], easy to use from:\n\n- [Jupyter notebooks with the Kotlin kernel][29]\n- [Kotlin scripts (`kts`)][27]\n- [Kotlin projects][28]\n\n```kotlin\nval api = DevelocityApi.newInstance()\napi.buildsApi.getBuildsFlow(fromInstant = 0, query = \"buildStartTime\u003c-1d\").forEach {\n  println(it)\n}\n```\n\n## How is this different from the [official samples][33]?\n\nThe official samples are an excellent demo of the API inside a full-fledged Java project.\nAmong other things, you might not want to maintain an OpenAPI code generation setup.\nEven if you do, you'll find it generates less-than-ideal or even failing code depending on your `openapi-generator` configuration.\nThis library [fixes][34] those issues in generated code, implements [paging][24], [caching][13] and [env-based configuration][8] for you, while providing a JAR that's ready-to-use from any project, script or notebook.\n\n## Setup\n\nSet up environment variables and use the library from any notebook, script or project:\n\n- [`DEVELOCITY_API_URL`][16]: the URL of your Develocity instance\n- [`DEVELOCITY_API_TOKEN`][17]: an [access key][31] for the Develocity instance\n- [`DEVELOCITY_API_CACHE_ENABLED`][12] (optional, off by default): enables caching for some\n  requests (see [caveats][13])\n\n### Setup snippets\n\n\u003cdetails\u003e\n  \u003csummary\u003eAdd to a Jupyter notebook\u003c/summary\u003e\n\n```\n%useLatestDescriptors\n%use develocity-api-kotlin(version=2024.3.0)\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eAdd to a Kotlin script\u003c/summary\u003e\n\n```kotlin\n@file:DependsOn(\"com.gabrielfeo:develocity-api-kotlin:2024.3.0\")\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eAdd to a Kotlin project\u003c/summary\u003e\n\n```kotlin\ndependencies {\n  implementation(\"com.gabrielfeo:develocity-api-kotlin:2024.3.0\")\n}\n```\n\n\u003c/details\u003e\n\n## Usage\n\nThe [`DevelocityApi`][9] interface represents the Develocity REST API. It contains\nall the APIs exactly as listed in the [REST API Manual][5]:\n\n```kotlin\ninterface DevelocityApi {\n  val buildsApi: BuildsApi\n  val testsApi: TestsApi\n  val buildCacheApi: BuildCacheApi\n  val projectsApi: ProjectsApi\n  val metaApi: MetaApi\n  val testDistributionApi: TestDistributionApi\n  val authApi: AuthApi\n  // ...\n}\n```\n\nFor example, [`BuildsApi`][20] contains all endpoints under `/api/builds/`:\n\n- [`BuildsApi.getBuilds`][21]: `GET /api/builds`\n- [`BuildsApi.getGradleAttributes`][22]: `GET /api/builds/{id}/gradle-attributes`\n- ...\n\n### Calling the APIs\n\nAPI methods are generated as suspend functions.\nFor most cases like scripts and notebooks, simply use [runBlocking][30]:\n\n```kotlin\nrunBlocking {\n  val builds: List\u003cBuild\u003e = api.buildsApi.getBuilds(fromInstant = 0, query = \"...\")\n}\n```\n\n### Caching\n\nHTTP caching is available, which can speed up queries significantly, but is\noff by default. Enable by simply setting [`DEVELOCITY_API_CACHE_ENABLED`][12] to `true`. See\n[`CacheConfig`][13] for caveats.\n\n### Extensions\n\nExplore the library's convenience extensions:\n[`com.gabrielfeo.develocity.api.extension`][25].\n\nBy default, the API's most common endpoint, `/api/builds`, is paginated. The library provides a\n[`getBuildsFlow`][24] extension to handle paging under-the-hood and yield all builds as you collect\nthem:\n\n```kotlin\nval builds: Flow\u003cBuild\u003e = api.buildsApi.getBuildsFlow(fromInstant = 0, query = \"...\")\nbuilds.collect {\n  // ...\n}\n```\n\n### Shutdown\n\nBy default, the library keeps some of its resources (like threads) alive until idle, in\ncase they're needed again. This is an optimization of [OkHttp][4]. If you're working on a notebook\nor have a long-living program that fetches builds continuosly, no shutdown is needed.\n\n```kotlin\nval api = DevelocityApi.newInstance()\nwhile (true) {\n  delay(2.minutes)\n  processNewBuilds(api.buildsApi.getBuildsFlow(query = \"...\"))\n  // Don't worry about shutdown\n}\n```\n\nIn other cases (i.e. fetching some builds and exiting), you might want to call\n[`DevelocityApi.shutdown()`][11] so that the program exits immediately:\n\n```kotlin\nval api = DevelocityApi.newInstance()\nprintMetrics(api.buildsApi.getBuildsFlow(query = \"...\"))\n// Call shutdown if you expect the program to exit now\napi.shutdown()\n```\n\n### Working samples\n\n- [Jupyter notebooks with the Kotlin kernel][29]\n- [Kotlin scripts (`kts`)][27]\n- [Kotlin projects][28]\n\n## Documentation\n\n[![Javadoc](https://img.shields.io/badge/javadoc-latest-orange)][7]\n\nThe javadoc of API interfaces and models, such as [`BuildsApi`][18] and [`GradleAttributes`][19],\nmatches the [REST API Manual][5] exactly. Both these classes and Gradle's own manual are generated\nfrom the same OpenAPI spec.\n\n## Optional setup\n\nCreating a custom [`Config`][8] allows you to change library settings via code instead of\nenvironment variables. It also lets you share resources between the library's `OkHttpClient` and\nyour own. For example:\n\n```kotlin\nval config = Config(\n  apiUrl = \"https://ge.mycompany.com/api/\",\n  apiToken = { vault.getGeApiToken() },\n  clientBuilder = existingClient.newBuilder(),\n)\nval api = DevelocityApi.newInstance(config)\napi.buildsApi.getBuilds(fromInstant = yesterdayMilli)\n```\n\nSee the [`Config`][8] documentation for more.\n\n## More info\n\n- Use JDK 8 or 14+ to run, if you want to avoid the [\"illegal reflective access\" warning about\n  Retrofit][3]\n- All classes live in these packages. If you need to make small edits to scripts where there's\n  no auto-complete, wildcard imports can be used (in notebooks, they're added automatically):\n\n```kotlin\nimport com.gabrielfeo.develocity.api.*\nimport com.gabrielfeo.develocity.api.model.*\nimport com.gabrielfeo.develocity.api.model.extension.*\n```\n\n## Issues and contributions\n\nIf you run into any problems, please open an issue to make it visible to maintainers and other users.\nContributions are always welcome, although it's recommended to open an issue first.\nFor general discussions or questions, feel free to reach out to maintainers on the [Gradle Community Slack][35].\n\n[1]: https://docs.gradle.com/enterprise/api-manual/\n[2]: https://square.github.io/retrofit/\n[3]: https://github.com/square/retrofit/issues/3448\n[4]: https://github.com/square/retrofit/issues/3144#issuecomment-508300518\n[5]: https://docs.gradle.com/enterprise/api-manual/ref/2024.1.html\n[6]: https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator-gradle-plugin/README.adoc\n[7]: https://gabrielfeo.github.io/develocity-api-kotlin/\n[8]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-config/index.html\n[9]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-develocity-api/\n[11]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-develocity-api/shutdown.html\n[12]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-config/-cache-config/cache-enabled.html\n[13]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-config/-cache-config/index.html\n[14]: https://central.sonatype.com/artifact/com.gabrielfeo/develocity-api-kotlin/2024.3.0\n[16]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-config/api-url.html\n[17]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-config/api-token.html\n[18]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-builds-api/index.html\n[19]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api.model/-gradle-attributes/index.html\n[20]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-builds-api/index.html\n[21]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-builds-api/get-builds.html\n[22]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-builds-api/get-gradle-attributes.html\n[23]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-develocity-api/-default-instance/index.html\n[24]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api.extension/get-builds-flow.html\n[25]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api.extension/index.html\n[26]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/\n[27]: ./examples/example-scripts/example-script.main.kts\n[28]: ./examples/example-project\n[29]: https://nbviewer.org/github/gabrielfeo/develocity-api-kotlin/blob/main/examples/example-notebooks/MostFrequentBuilds.ipynb\n[30]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/run-blocking.html\n[31]: ./docs/AccessKeys.md\n[32]: ./examples\n[33]: https://github.com/gradle/develocity-api-samples\n[34]: https://github.com/gabrielfeo/develocity-api-kotlin/blob/main/build-logic/src/functionalTest/kotlin/com/gabrielfeo/task/PostProcessGeneratedApiTest.kt#L21\n[35]: https://community.gradle.org/#community-channels\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgabrielfeo%2Fdevelocity-api-kotlin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgabrielfeo%2Fdevelocity-api-kotlin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgabrielfeo%2Fdevelocity-api-kotlin/lists"}