https://github.com/gabrielfeo/develocity-api-kotlin
A library to use the Develocity API in Kotlin notebooks and more
https://github.com/gabrielfeo/develocity-api-kotlin
develocity gradle gradle-enterprise jupyter jupyter-notebooks kotlin kotlin-notebook kotlin-scripts openapi-generator
Last synced: 3 months ago
JSON representation
A library to use the Develocity API in Kotlin notebooks and more
- Host: GitHub
- URL: https://github.com/gabrielfeo/develocity-api-kotlin
- Owner: gabrielfeo
- License: mit
- Created: 2022-12-16T18:34:48.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-04-12T22:35:00.000Z (about 1 year ago)
- Last Synced: 2024-04-13T16:33:24.054Z (about 1 year ago)
- Topics: develocity, gradle, gradle-enterprise, jupyter, jupyter-notebooks, kotlin, kotlin-notebook, kotlin-scripts, openapi-generator
- Language: Kotlin
- Homepage: https://gabrielfeo.github.io/develocity-api-kotlin/
- Size: 4.44 MB
- Stars: 15
- Watchers: 3
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Develocity API Kotlin
[][14]
[][7]
(formerly `gradle-enterprise-api-kotlin`)
A Kotlin library to access the [Develocity API][1], easy to use from:
- [Jupyter notebooks with the Kotlin kernel][29]
- [Kotlin scripts (`kts`)][27]
- [Kotlin projects][28]
```kotlin
val api = DevelocityApi.newInstance()
api.buildsApi.getBuildsFlow(fromInstant = 0, query = "buildStartTime<-1d").forEach {
println(it)
}
```
## How is this different from the [official samples][33]?
The official samples are an excellent demo of the API inside a full-fledged Java project.
Among other things, you might not want to maintain an OpenAPI code generation setup.
Even if you do, you'll find it generates less-than-ideal or even failing code depending on your `openapi-generator` configuration.
This 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.
## Setup
Set up environment variables and use the library from any notebook, script or project:
- [`DEVELOCITY_API_URL`][16]: the URL of your Develocity instance
- [`DEVELOCITY_API_TOKEN`][17]: an [access key][31] for the Develocity instance
- [`DEVELOCITY_API_CACHE_ENABLED`][12] (optional, off by default): enables caching for some
requests (see [caveats][13])
### Setup snippets
Add to a Jupyter notebook
```
%useLatestDescriptors
%use develocity-api-kotlin(version=2024.3.0)
```
Add to a Kotlin script
```kotlin
@file:DependsOn("com.gabrielfeo:develocity-api-kotlin:2024.3.0")
```
Add to a Kotlin project
```kotlin
dependencies {
implementation("com.gabrielfeo:develocity-api-kotlin:2024.3.0")
}
```
## Usage
The [`DevelocityApi`][9] interface represents the Develocity REST API. It contains
all the APIs exactly as listed in the [REST API Manual][5]:
```kotlin
interface DevelocityApi {
val buildsApi: BuildsApi
val testsApi: TestsApi
val buildCacheApi: BuildCacheApi
val projectsApi: ProjectsApi
val metaApi: MetaApi
val testDistributionApi: TestDistributionApi
val authApi: AuthApi
// ...
}
```
For example, [`BuildsApi`][20] contains all endpoints under `/api/builds/`:
- [`BuildsApi.getBuilds`][21]: `GET /api/builds`
- [`BuildsApi.getGradleAttributes`][22]: `GET /api/builds/{id}/gradle-attributes`
- ...
### Calling the APIs
API methods are generated as suspend functions.
For most cases like scripts and notebooks, simply use [runBlocking][30]:
```kotlin
runBlocking {
val builds: List = api.buildsApi.getBuilds(fromInstant = 0, query = "...")
}
```
### Caching
HTTP caching is available, which can speed up queries significantly, but is
off by default. Enable by simply setting [`DEVELOCITY_API_CACHE_ENABLED`][12] to `true`. See
[`CacheConfig`][13] for caveats.
### Extensions
Explore the library's convenience extensions:
[`com.gabrielfeo.develocity.api.extension`][25].
By default, the API's most common endpoint, `/api/builds`, is paginated. The library provides a
[`getBuildsFlow`][24] extension to handle paging under-the-hood and yield all builds as you collect
them:
```kotlin
val builds: Flow = api.buildsApi.getBuildsFlow(fromInstant = 0, query = "...")
builds.collect {
// ...
}
```
### Shutdown
By default, the library keeps some of its resources (like threads) alive until idle, in
case they're needed again. This is an optimization of [OkHttp][4]. If you're working on a notebook
or have a long-living program that fetches builds continuosly, no shutdown is needed.
```kotlin
val api = DevelocityApi.newInstance()
while (true) {
delay(2.minutes)
processNewBuilds(api.buildsApi.getBuildsFlow(query = "..."))
// Don't worry about shutdown
}
```
In other cases (i.e. fetching some builds and exiting), you might want to call
[`DevelocityApi.shutdown()`][11] so that the program exits immediately:
```kotlin
val api = DevelocityApi.newInstance()
printMetrics(api.buildsApi.getBuildsFlow(query = "..."))
// Call shutdown if you expect the program to exit now
api.shutdown()
```
### Working samples
- [Jupyter notebooks with the Kotlin kernel][29]
- [Kotlin scripts (`kts`)][27]
- [Kotlin projects][28]
## Documentation
[][7]
The javadoc of API interfaces and models, such as [`BuildsApi`][18] and [`GradleAttributes`][19],
matches the [REST API Manual][5] exactly. Both these classes and Gradle's own manual are generated
from the same OpenAPI spec.
## Optional setup
Creating a custom [`Config`][8] allows you to change library settings via code instead of
environment variables. It also lets you share resources between the library's `OkHttpClient` and
your own. For example:
```kotlin
val config = Config(
apiUrl = "https://ge.mycompany.com/api/",
apiToken = { vault.getGeApiToken() },
clientBuilder = existingClient.newBuilder(),
)
val api = DevelocityApi.newInstance(config)
api.buildsApi.getBuilds(fromInstant = yesterdayMilli)
```
See the [`Config`][8] documentation for more.
## More info
- Use JDK 8 or 14+ to run, if you want to avoid the ["illegal reflective access" warning about
Retrofit][3]
- All classes live in these packages. If you need to make small edits to scripts where there's
no auto-complete, wildcard imports can be used (in notebooks, they're added automatically):
```kotlin
import com.gabrielfeo.develocity.api.*
import com.gabrielfeo.develocity.api.model.*
import com.gabrielfeo.develocity.api.model.extension.*
```
## Issues and contributions
If you run into any problems, please open an issue to make it visible to maintainers and other users.
Contributions are always welcome, although it's recommended to open an issue first.
For general discussions or questions, feel free to reach out to maintainers on the [Gradle Community Slack][35].
[1]: https://docs.gradle.com/enterprise/api-manual/
[2]: https://square.github.io/retrofit/
[3]: https://github.com/square/retrofit/issues/3448
[4]: https://github.com/square/retrofit/issues/3144#issuecomment-508300518
[5]: https://docs.gradle.com/enterprise/api-manual/ref/2024.1.html
[6]: https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator-gradle-plugin/README.adoc
[7]: https://gabrielfeo.github.io/develocity-api-kotlin/
[8]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-config/index.html
[9]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-develocity-api/
[11]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-develocity-api/shutdown.html
[12]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-config/-cache-config/cache-enabled.html
[13]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-config/-cache-config/index.html
[14]: https://central.sonatype.com/artifact/com.gabrielfeo/develocity-api-kotlin/2024.3.0
[16]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-config/api-url.html
[17]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-config/api-token.html
[18]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-builds-api/index.html
[19]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api.model/-gradle-attributes/index.html
[20]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-builds-api/index.html
[21]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-builds-api/get-builds.html
[22]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-builds-api/get-gradle-attributes.html
[23]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-develocity-api/-default-instance/index.html
[24]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api.extension/get-builds-flow.html
[25]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api.extension/index.html
[26]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/
[27]: ./examples/example-scripts/example-script.main.kts
[28]: ./examples/example-project
[29]: https://nbviewer.org/github/gabrielfeo/develocity-api-kotlin/blob/main/examples/example-notebooks/MostFrequentBuilds.ipynb
[30]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/run-blocking.html
[31]: ./docs/AccessKeys.md
[32]: ./examples
[33]: https://github.com/gradle/develocity-api-samples
[34]: https://github.com/gabrielfeo/develocity-api-kotlin/blob/main/build-logic/src/functionalTest/kotlin/com/gabrielfeo/task/PostProcessGeneratedApiTest.kt#L21
[35]: https://community.gradle.org/#community-channels