# 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

# 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.

      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.

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

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.

  //  - For example, the "SHA-1" algorithm might be referred to as "SHA1".
  //  - The algorithm name is not case-sensitive.
  @SuppressWarnings("deprecation") // We still need to test our deprecated APIs.
  private static final ImmutableMap<String, HashFunction> ALGORITHMS =
      new ImmutableMap.Builder<String, HashFunction>()
          .put("MD5", md5())
          .put("SHA", sha1()) // Not the official name, but still works

## About security, APIs, and docs { #about-security-apis-and-docs }

Hiding your documentation user interfaces in production *shouldn't* be the way to protect your API.

That doesn't add any extra security to your API, the *path operations* will still be available where they are.

If there's a security flaw in your code, it will still exist.

  //  - For example, the "SHA-1" algorithm might be referred to as "SHA1".
  //  - The algorithm name is not case-sensitive.
  @SuppressWarnings("deprecation") // We still need to test our deprecated APIs.
  private static final ImmutableMap<String, HashFunction> ALGORITHMS =
      new ImmutableMap.Builder<String, HashFunction>()
          .put("MD5", md5())
          .put("SHA", sha1()) // Not the official name, but still works

The hierarchy is like:

* **Uvicorn**: an ASGI server
    * **Starlette**: (uses Uvicorn) a web microframework
        * **FastAPI**: (uses Starlette) an API microframework with several additional features for building APIs, with data validation, etc.

* **Uvicorn**:
    * Will have the best performance, as it doesn't have much extra code apart from the server itself.