Skip to content

Commit 7d71888

Browse files
gabrielfeogabrielfeo
authored
Update README (#69)
Update the README following #49, #67 and #68.
1 parent 4417d1e commit 7d71888

File tree

1 file changed

+94
-76
lines changed

1 file changed

+94
-76
lines changed

‎README.md‎

Lines changed: 94 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -1,133 +1,151 @@
11
# Gradle Enterprise API Kotlin
22

33
[![Release](https://jitpack.io/v/gabrielfeo/gradle-enterprise-api-kotlin.svg)][14]
4-
[![Javadoc](https://img.shields.io/badge/javadoc-latest-orange)][15]
4+
[![Javadoc](https://img.shields.io/badge/javadoc-latest-orange)][7]
55

66
A Kotlin library to access the [Gradle Enterprise API][1], easy to use from Kotlin
7-
scripts:
7+
scripts, projects or Jupyter notebooks:
88

99
```kotlin
10-
gradleEnterpriseApi.getBuilds(since = yesterday).forEach {
10+
GradleEnterprise.buildsApi.getBuilds(since = yesterdayMilli).forEach {
1111
println(it)
1212
}
1313
```
1414

1515
## Setup
1616

17-
Set up once and use the library from any script in your machine:
17+
Set up once and use the library from anywhere in your machine:
1818

1919
- [`GRADLE_ENTERPRISE_API_URL`][16] environment variable: the URL of your Gradle Enterprise instance
2020
- [`GRADLE_ENTERPRISE_API_TOKEN`][17] environment variable: an API access token for the Gradle
21-
Enterprise instance. Alternatively, can be a macOS keychain entry labeled
22-
`gradle-enterprise-api-token` (recommended).
21+
Enterprise instance.
22+
- Or a macOS keychain entry labeled `gradle-enterprise-api-token` (recommended).
2323

24-
That's it! From any `kts` script, you can add a dependency on the library and start querying the
25-
API:
24+
That's it! You can now use the library without any code configuration from:
2625

27-
```kotlin
28-
@file:Repository("https://jitpack.io")
29-
@file:DependsOn("com.github.gabrielfeo:gradle-enterprise-api-kotlin:1.0")
26+
- [Kotlin scripts (`kts`)](./examples/example-script.main.kts)
27+
- [Kotlin projects](./examples/example-project)
28+
- [Jupyter notebooks with the Kotlin kernel](./examples/example-notebooks)
29+
30+
## Usage
3031

31-
gradleEnterpriseApi.getBuild(id = "hy5nxbzfjxe5k")
32+
The [`GradleEnterpriseApi`][9] interface represents the Gradle Enterprise REST API. It contains
33+
the 4 APIs exactly as listed in the [REST API Manual][5]:
34+
35+
```kotlin
36+
interface GradleEnterpriseApi {
37+
val buildsApi: BuildsApi
38+
val buildCacheApi: BuildCacheApi
39+
val metaApi: MetaApi
40+
val testDistributionApi: TestDistributionApi
41+
}
3242
```
3343

34-
For configuring base URL and token via code and other available options, see the
35-
[`options` object][8]. HTTP caching is available, which can speed up queries significantly, but is
36-
off by default. Enable with [`GRADLE_ENTERPRISE_API_CACHE_ENABLED`][12]. See [`CacheOptions`][13]
37-
for caveats.
44+
For example, [`BuildsApi`][20] contains all endpoints under `/api/builds/`:
3845

39-
<details>
40-
<summary>Setup in full projects (non-scripts)</summary>
46+
- [`BuildsApi.getBuilds`][21]: `GET /api/builds`
47+
- [`BuildsApi.getGradleAttributes`][22]: `GET /api/builds/{id}/gradle-attributes`
48+
- ...
4149

42-
You can also use it in a full Kotlin project instead of a script. Just add a dependency:
50+
### Calling the APIs
4351

44-
```kotlin
45-
repositories {
46-
maven(url = "https://jitpack.io")
47-
}
48-
dependencies {
49-
implementation("com.github.gabrielfeo:gradle-enterprise-api-kotlin:1.0")
50-
}
51-
```
52+
For simple use cases, you may use the companion instance ([DefaultInstance][23]) directly, as if
53+
calling static methods:
5254

53-
<details>
54-
<summary>Groovy</summary>
55+
```kotlin
56+
GradleEnterpriseApi.buildsApi.getBuilds(since = yesterdayMilli)
57+
```
5558

56-
```groovy
57-
repositories {
58-
maven { url = 'https://jitpack.io' }
59-
}
60-
dependencies {
61-
implementation 'com.github.gabrielfeo:gradle-enterprise-api-kotlin:1.0'
62-
}
63-
```
59+
It's recommended to call [`GradleEnterpriseApi.shutdown()`][11] at the end of scripts to release
60+
resources and let the program exit. Otherwise, it'll keep running for an extra ~60s after code
61+
finishes, as an [expected behavior of OkHttp][4].
6462

65-
</details>
66-
</details>
63+
### Caching
6764

68-
## Usage
65+
HTTP caching is available, which can speed up queries significantly, but is
66+
off by default. Enable by simply setting [`GRADLE_ENTERPRISE_API_CACHE_ENABLED`][12] to `true`. See
67+
[`CacheConfig`][13] for caveats.
6968

70-
API endpoints are provided as a single interface: [`GradleEnterpriseApi`][9]. The Javadoc is a
71-
the same as Gradle's online docs, as they're generated from the same spec. An instance is
72-
initialized and ready-to-use as the global `gradleEnterpriseApi` instance:
69+
### Extensions
7370

74-
```kotlin
75-
gradleEnterpriseApi.getBuild(id = "hy5nxbzfjxe5k")
76-
```
71+
Explore the library's convenience extensions:
72+
[`com.gabrielfeo.gradle.enterprise.api.extension`][25].
7773

78-
The library also provides a few extension functions on top of the regular API, such as paged
79-
requests and joining. See [`GradleEnterpriseApi` extensions][10].
74+
What you'll probably use the most is [`getGradleAttributesFlow`][24], which will call
75+
`/api/builds` to get the list of build IDs since a given date and join each with
76+
`/api/builds/{id}/gradle-attributes`, which contains tags and custom values on each build. It
77+
also takes care of paging under-the-hood, returning a [`Flow`][26] of all builds since the given
78+
date, so you don't have to worry about the REST API's limit of 1000 builds per request:
8079

8180
```kotlin
82-
// Standard query to /api/builds, limited to 1000 builds server-side
83-
gradleEnterpriseApi.getBuilds(since = lastMonth)
84-
// Extension: Streams all available builds since given date (paging underneath)
85-
gradleEnterpriseApi.getBuildsFlow(since = lastMonth)
81+
val builds = GradleEnterpriseApi.buildsApi.getGradleAttributesFlow(since = lastYear)
82+
builds.collect {
83+
// ...
84+
}
8685
```
8786

88-
It's recommended to call [`shutdown()`][11] at the end of scripts to release resources and let the
89-
program exit. Otherwise, it'll keep running for an extra ~60s after code finishes, as an [expected
90-
behavior of OkHttp][4].
87+
## Documentation
88+
89+
[![Javadoc](https://img.shields.io/badge/javadoc-latest-orange)][7]
90+
91+
The javadoc of API interfaces and models, such as [`BuildsApi`][18] and [`GradleAttributes`][19],
92+
matches the [REST API Manual][5] exactly. Both these classes and Gradle's own manual are generated
93+
from the same OpenAPI spec.
94+
95+
## Optional setup
96+
97+
Creating a custom [`Config`][8] allows you to change library settings via code instead of
98+
environment variables. It also lets you share resource between the library's `OkHttpClient` and
99+
your own. For example:
91100

92101
```kotlin
93-
val builds = gradleEnterpriseApi.getBuilds()
94-
// do work ...
95-
shutdown()
102+
val config = Config(
103+
apiUrl = "https://ge.mycompany.com/api/",
104+
apiToken = { vault.getGeApiToken() },
105+
clientBuilder = existingClient.newBuilder(),
106+
)
107+
val api = GradleEnterpriseApi.newInstance(config)
108+
api.buildsApi.getBuilds(since = yesterdayMilli)
96109
```
97110

111+
See the [`Config`][8] documentation for more.
112+
98113
## More info
99114

100-
- Currently built for Gradle Enterprise `2022.4`, but should work fine with previous versions.
115+
- Currently built for Gradle Enterprise `2022.4`, but should work fine with previous and
116+
future versions. The library will be updated regularly for new API versions.
101117
- Use JDK 8 or 14+ to run, if you want to avoid the ["illegal reflective access" warning about
102118
Retrofit][3]
103-
- All classes live in these two packages. If you need to make small edits to scripts where
104-
there's no auto-complete, wildcard imports can be used:
119+
- All classes live in these packages. If you need to make small edits to scripts where there's
120+
no auto-complete, wildcard imports can be used:
105121

106122
```kotlin
107123
import com.gabrielfeo.gradle.enterprise.api.*
108124
import com.gabrielfeo.gradle.enterprise.api.model.*
109125
import com.gabrielfeo.gradle.enterprise.api.model.extension.*
110126
```
111127

112-
### Internals
113-
114-
API classes such as `GradleEnterpriseApi` and response models are generated from the offical
115-
[API spec][5], using the [OpenAPI Generator Gradle Plugin][6].
116-
117128
[1]: https://docs.gradle.com/enterprise/api-manual/
118129
[2]: https://square.github.io/retrofit/
119130
[3]: https://github.com/square/retrofit/issues/3448
120131
[4]: https://github.com/square/retrofit/issues/3144#issuecomment-508300518
121-
[5]: https://docs.gradle.com/enterprise/api-manual/#reference_documentation
132+
[5]: https://docs.gradle.com/enterprise/api-manual/ref/2022.4.html
122133
[6]: https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator-gradle-plugin/README.adoc
123134
[7]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/
124-
[8]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/gradle-enterprise-api-kotlin/com.gabrielfeo.gradle.enterprise.api/options.html
125-
[9]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/gradle-enterprise-api-kotlin/com.gabrielfeo.gradle.enterprise.api/-gradle-enterprise-api/
126-
[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
127-
[11]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/gradle-enterprise-api-kotlin/com.gabrielfeo.gradle.enterprise.api/shutdown.html
128-
[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
129-
[13]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/gradle-enterprise-api-kotlin/com.gabrielfeo.gradle.enterprise.api/-options/-cache-options/index.html
135+
[8]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api/-config/index.html
136+
[9]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api/-gradle-enterprise-api/
137+
[11]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api/-gradle-enterprise-api/shutdown.html
138+
[12]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api/-config/-cache-config/cache-enabled.html
139+
[13]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api/-config/-cache-config/index.html
130140
[14]: https://jitpack.io/#gabrielfeo/gradle-enterprise-api-kotlin
131-
[15]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/
132-
[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
133-
[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
141+
[16]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api/-config/api-url.html
142+
[17]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api/-config/api-token.html
143+
[18]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api/-builds-api/index.html
144+
[19]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api.model/-gradle-attributes/index.html
145+
[20]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api/-builds-api/index.html
146+
[21]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api/-builds-api/get-builds.html
147+
[22]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api/-builds-api/get-gradle-attributes.html
148+
[23]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api/-gradle-enterprise-api/-default-instance/index.html
149+
[24]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api.extension/get-gradle-attributes-flow.html
150+
[25]: https://gabrielfeo.github.io/gradle-enterprise-api-kotlin/library/com.gabrielfeo.gradle.enterprise.api.extension/index.html
151+
[26]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/

0 commit comments

Comments
 (0)