# ADR-0006 - Use of Provider APIs in Gradle

## Status

- ACCEPTED on 2024-06-21

## Context

* **Consistency with dependencies**: Gradle's ecosystem and dependencies predominantly use American English

### Exceptions

Some legitimate exceptions exist where British English or other variants must be preserved:

* **Third-party APIs and libraries**: When integrating with external APIs that use different spelling conventions

        .build()
    val call = client.newCall(request)

    // Check the Kotlin-focused APIs.
    assertThat(call.tag(String::class)).isEqualTo("hello")
    assertThat(call.tag(Integer::class)).isEqualTo(5)
    assertThat(call.tag(Boolean::class)).isNull()
    assertThat(call.tag(Any::class)).isNull()

    // Check the Java APIs too.
    assertThat(call.tag(String::class.java)).isEqualTo("hello")

# ADR-0003 - Avoid introducing Groovy types to public API

## Status

- ACCEPTED on 2024-01-12

## Context

Gradle's public API requires equal access from all JVM-based languages.
Kotlin, Groovy, Java, and other JVM-based languages should be able to use the Gradle API without relying on another language's standard library.

Historically, Gradle has shipped with some Groovy types in very prominent APIs.

## Version 5.0.0-alpha.17

_2025-06-29_

This release stabilizes many APIs for the imminent OkHttp 5.0.0 release.

 *  New: `TrailersSource`, a public API for HTTP trailers. Production callers shouldn't need this
    as the API to read response trailers is unchanged. Testers may use this new stable API to
    supply trailers for a `Response`.

    val builtRequestWithoutCache = requestWithoutCache.newBuilder().url("http://localhost/api/foo").build()
    assertThat(builtRequestWithoutCache.url).isEqualTo(
      "http://localhost/api/foo".toHttpUrl(),
    )
    val requestWithCache =
      Request
        .Builder()
        .url("http://localhost/api")
        .build()
    // cache url object

      When doing so, still annotate nullable parameters and the return type as `@Nullable`.
  * Do not use `@Contract` for public APIs.
  * For polynull public APIs, the solution has to be decided on a case-by-case basis.

Do not remove `null` checks on public API boundaries, even if the annotations (or rather lack of them) suggest this.
Not all client code is compiled with NullAway.

The main feature I wanted from Django REST Framework was the automatic API documentation.

Then I found that there was a standard to document APIs, using JSON (or YAML, an extension of JSON) called Swagger.

And there was a web user interface for Swagger APIs already created. So, being able to generate Swagger documentation for an API would allow using this web user interface automatically.

things you should know about contributing:

1.  API changes require discussion, use cases, etc. Code comes later.
2.  Pull requests are great for small fixes for bugs, documentation, etc.
3.  Pull requests are not merged directly into the master branch.
4.  Code contributions require signing a Google CLA.

API changes
-----------

We make changes to Guava's public [APIs][], including adding new APIs, very

  fun uninitializedURI() {
    val request = Request.Builder().url("http://localhost/api").build()
    assertThat(request.url.toUri()).isEqualTo(URI("http://localhost/api"))
    assertThat(request.url).isEqualTo("http://localhost/api".toHttpUrl())
  }

  @Test
  fun newBuilderUrlResetsUrl() {
    val requestWithoutCache = Request.Builder().url("http://localhost/api").build()