From 88bb149d74bf98387917810297fe756bdc187046 Mon Sep 17 00:00:00 2001 From: Gabriel Feo Date: Tue, 23 May 2023 17:47:27 +0100 Subject: [PATCH] Misc changes --- README.md | 170 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 94 insertions(+), 76 deletions(-) diff --git a/README.md b/README.md index a1e89a686..d08b93022 100644 --- a/README.md +++ b/README.md @@ -1,107 +1,123 @@ # Gradle Enterprise API Kotlin [![Release](https://jitpack.io/v/gabrielfeo/gradle-enterprise-api-kotlin.svg)][14] -[![Javadoc](https://img.shields.io/badge/javadoc-latest-orange)][15] +[![Javadoc](https://img.shields.io/badge/javadoc-latest-orange)][7] A Kotlin library to access the [Gradle Enterprise API][1], easy to use from Kotlin -scripts: +scripts, projects or Jupyter notebooks: ```kotlin -gradleEnterpriseApi.getBuilds(since = yesterday).forEach { +GradleEnterprise.buildsApi.getBuilds(since = yesterdayMilli).forEach { println(it) } ``` ## Setup -Set up once and use the library from any script in your machine: +Set up once and use the library from anywhere in your machine: - [`GRADLE_ENTERPRISE_API_URL`][16] environment variable: the URL of your Gradle Enterprise instance - [`GRADLE_ENTERPRISE_API_TOKEN`][17] environment variable: an API access token for the Gradle - Enterprise instance. Alternatively, can be a macOS keychain entry labeled - `gradle-enterprise-api-token` (recommended). + Enterprise instance. + - Or a macOS keychain entry labeled `gradle-enterprise-api-token` (recommended). -That's it! From any `kts` script, you can add a dependency on the library and start querying the -API: +That's it! You can now use the library without any code configuration from: -```kotlin -@file:Repository("https://jitpack.io") -@file:DependsOn("com.github.gabrielfeo:gradle-enterprise-api-kotlin:1.0") +- [Kotlin scripts (`kts`)](./examples/example-script.main.kts) +- [Kotlin projects](./examples/example-project) +- [Jupyter notebooks with the Kotlin kernel](./examples/example-notebooks) + +## Usage -gradleEnterpriseApi.getBuild(id = "hy5nxbzfjxe5k") +The [`GradleEnterpriseApi`][9] interface represents the Gradle Enterprise REST API. It contains +the 4 APIs exactly as listed in the [REST API Manual][5]: + +```kotlin +interface GradleEnterpriseApi { + val buildsApi: BuildsApi + val buildCacheApi: BuildCacheApi + val metaApi: MetaApi + val testDistributionApi: TestDistributionApi +} ``` -For configuring base URL and token via code and other available options, see the -[`options` object][8]. HTTP caching is available, which can speed up queries significantly, but is -off by default. Enable with [`GRADLE_ENTERPRISE_API_CACHE_ENABLED`][12]. See [`CacheOptions`][13] -for caveats. +For example, [`BuildsApi`][20] contains all endpoints under `/api/builds/`: -
- Setup in full projects (non-scripts) +- [`BuildsApi.getBuilds`][21]: `GET /api/builds` +- [`BuildsApi.getGradleAttributes`][22]: `GET /api/builds/{id}/gradle-attributes` +- ... - You can also use it in a full Kotlin project instead of a script. Just add a dependency: +### Calling the APIs - ```kotlin - repositories { - maven(url = "https://jitpack.io") - } - dependencies { - implementation("com.github.gabrielfeo:gradle-enterprise-api-kotlin:1.0") - } - ``` +For simple use cases, you may use the companion instance ([DefaultInstance][23]) directly, as if +calling static methods: -
- Groovy +```kotlin +GradleEnterpriseApi.buildsApi.getBuilds(since = yesterdayMilli) +``` - ```groovy - repositories { - maven { url = 'https://jitpack.io' } - } - dependencies { - implementation 'com.github.gabrielfeo:gradle-enterprise-api-kotlin:1.0' - } - ``` +It's recommended to call [`GradleEnterpriseApi.shutdown()`][11] at the end of scripts to release +resources and let the program exit. Otherwise, it'll keep running for an extra ~60s after code +finishes, as an [expected behavior of OkHttp][4]. -
-
+### Caching -## Usage +HTTP caching is available, which can speed up queries significantly, but is +off by default. Enable by simply setting [`GRADLE_ENTERPRISE_API_CACHE_ENABLED`][12] to `true`. See +[`CacheConfig`][13] for caveats. -API endpoints are provided as a single interface: [`GradleEnterpriseApi`][9]. The Javadoc is a -the same as Gradle's online docs, as they're generated from the same spec. An instance is -initialized and ready-to-use as the global `gradleEnterpriseApi` instance: +### Extensions -```kotlin -gradleEnterpriseApi.getBuild(id = "hy5nxbzfjxe5k") -``` +Explore the library's convenience extensions: +[`com.gabrielfeo.gradle.enterprise.api.extension`][25]. -The library also provides a few extension functions on top of the regular API, such as paged -requests and joining. See [`GradleEnterpriseApi` extensions][10]. +What you'll probably use the most is [`getGradleAttributesFlow`][24], which will call +`/api/builds` to get the list of build IDs since a given date and join each with +`/api/builds/{id}/gradle-attributes`, which contains tags and custom values on each build. It +also takes care of paging under-the-hood, returning a [`Flow`][26] of all builds since the given +date, so you don't have to worry about the REST API's limit of 1000 builds per request: ```kotlin -// Standard query to /api/builds, limited to 1000 builds server-side -gradleEnterpriseApi.getBuilds(since = lastMonth) -// Extension: Streams all available builds since given date (paging underneath) -gradleEnterpriseApi.getBuildsFlow(since = lastMonth) +val builds = GradleEnterpriseApi.buildsApi.getGradleAttributesFlow(since = lastYear) +builds.collect { + // ... +} ``` -It's recommended to call [`shutdown()`][11] at the end of scripts to release resources and let the -program exit. Otherwise, it'll keep running for an extra ~60s after code finishes, as an [expected -behavior of OkHttp][4]. +## Documentation + +[![Javadoc](https://img.shields.io/badge/javadoc-latest-orange)][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 resource between the library's `OkHttpClient` and +your own. For example: ```kotlin -val builds = gradleEnterpriseApi.getBuilds() -// do work ... -shutdown() +val config = Config( + apiUrl = "https://ge.mycompany.com/api/", + apiToken = { vault.getGeApiToken() }, + clientBuilder = existingClient.newBuilder(), +) +val api = GradleEnterpriseApi.newInstance(config) +api.buildsApi.getBuilds(since = yesterdayMilli) ``` +See the [`Config`][8] documentation for more. + ## More info -- Currently built for Gradle Enterprise `2022.4`, but should work fine with previous versions. +- Currently built for Gradle Enterprise `2022.4`, but should work fine with previous and + future versions. The library will be updated regularly for new API versions. - 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 two packages. If you need to make small edits to scripts where - there's no auto-complete, wildcard imports can be used: +- 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: ```kotlin import com.gabrielfeo.gradle.enterprise.api.* @@ -109,25 +125,27 @@ import com.gabrielfeo.gradle.enterprise.api.model.* import com.gabrielfeo.gradle.enterprise.api.model.extension.* ``` -### Internals - -API classes such as `GradleEnterpriseApi` and response models are generated from the offical -[API spec][5], using the [OpenAPI Generator Gradle Plugin][6]. - [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/#reference_documentation +[5]: https://docs.gradle.com/enterprise/api-manual/ref/2022.4.html [6]: https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator-gradle-plugin/README.adoc [7]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/ -[8]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/gradle-enterprise-api-kotlin/com.gabrielfeo.gradle.enterprise.api/options.html -[9]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/gradle-enterprise-api-kotlin/com.gabrielfeo.gradle.enterprise.api/-gradle-enterprise-api/ -[10]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/gradle-enterprise-api-kotlin/com.gabrielfeo.gradle.enterprise.api/-gradle-enterprise-api/index.html#373241164%2FExtensions%2F769193423 -[11]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/gradle-enterprise-api-kotlin/com.gabrielfeo.gradle.enterprise.api/shutdown.html -[12]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/gradle-enterprise-api-kotlin/com.gabrielfeo.gradle.enterprise.api/-options/-cache-options/index.html#1054652077%2FProperties%2F769193423 -[13]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/gradle-enterprise-api-kotlin/com.gabrielfeo.gradle.enterprise.api/-options/-cache-options/index.html +[8]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api/-config/index.html +[9]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api/-gradle-enterprise-api/ +[11]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api/-gradle-enterprise-api/shutdown.html +[12]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api/-config/-cache-config/cache-enabled.html +[13]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api/-config/-cache-config/index.html [14]: https://jitpack.io/#gabrielfeo/gradle-enterprise-api-kotlin -[15]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/ -[16]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/gradle-enterprise-api-kotlin/com.gabrielfeo.gradle.enterprise.api/-options/-gradle-enterprise-instance-options/index.html#-259580834%2FProperties%2F769193423 -[17]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/gradle-enterprise-api-kotlin/com.gabrielfeo.gradle.enterprise.api/-options/-gradle-enterprise-instance-options/index.html#-42243308%2FProperties%2F769193423 +[16]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api/-config/api-url.html +[17]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api/-config/api-token.html +[18]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api/-builds-api/index.html +[19]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api.model/-gradle-attributes/index.html +[20]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api/-builds-api/index.html +[21]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api/-builds-api/get-builds.html +[22]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api/-builds-api/get-gradle-attributes.html +[23]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api/-gradle-enterprise-api/-default-instance/index.html +[24]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api.extension/get-gradle-attributes-flow.html +[25]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api.extension/index.html +[26]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/