Skip to content

Update README #69

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 23, 2023
Merged

Update README #69

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
170 changes: 94 additions & 76 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,133 +1,151 @@
# 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/`:

<details>
<summary>Setup in full projects (non-scripts)</summary>
- [`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:

<details>
<summary>Groovy</summary>
```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].

</details>
</details>
### 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.*
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/