README.md

Develocity API Kotlin

(formerly gradle-enterprise-api-kotlin)

A Kotlin library to access the Develocity API, easy to use from:

• Jupyter notebooks with the Kotlin kernel
• Kotlin scripts (kts)
• Kotlin projects

val api = DevelocityApi.newInstance()
api.buildsApi.getBuildsFlow(fromInstant = 0, query = "buildStartTime<-1d").forEach {
  println(it)
}

The library takes care of caching under the hood (opt-in) and provides some convenience extensions.

Setup

Set up environment variables and use the library from any notebook, script or project:

• DEVELOCITY_API_URL: the URL of your Develocity instance
• DEVELOCITY_API_TOKEN: an access key for the Develocity instance
• DEVELOCITY_API_CACHE_ENABLED (optional, off by default): enables caching for some requests (see caveats)

Setup snippets

Add to a Jupyter notebook

%useLatestDescriptors
%use develocity-api-kotlin(version=2024.2.0)

Add to a Kotlin script

@file:DependsOn("com.gabrielfeo:develocity-api-kotlin:2024.2.0")

Add to a Kotlin project

dependencies {
  implementation("com.gabrielfeo:develocity-api-kotlin:2024.2.0")
}

Usage

The DevelocityApi interface represents the Develocity REST API. It contains all the APIs exactly as listed in the REST API Manual:

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 contains all endpoints under /api/builds/:

• BuildsApi.getBuilds: GET /api/builds
• BuildsApi.getGradleAttributes: 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:

runBlocking {
  val builds: List<Build> = 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 to true. See CacheConfig for caveats.

Extensions

Explore the library's convenience extensions: com.gabrielfeo.develocity.api.extension.

By default, the API's most common endpoint, /api/builds, is paginated. The library provides a getBuildsFlow extension to handle paging under-the-hood and yield all builds as you collect them:

val builds: Flow<Build> = 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. If you're working on a notebook or have a long-living program that fetches builds continuosly, no shutdown is needed.

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() so that the program exits immediately:

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
• Kotlin scripts (kts)
• Kotlin projects

Documentation

The javadoc of API interfaces and models, such as BuildsApi and GradleAttributes, matches the REST API Manual exactly. Both these classes and Gradle's own manual are generated from the same OpenAPI spec.

Optional setup

Creating a custom Config 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:

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 documentation for more.

More info

• Use JDK 8 or 14+ to run, if you want to avoid the "illegal reflective access" warning about Retrofit
• 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):

import com.gabrielfeo.develocity.api.*
import com.gabrielfeo.develocity.api.model.*
import com.gabrielfeo.develocity.api.model.extension.*