skip to content

What is Kotlin's Explicit API mode, and what two things does it require library authors to do?

level: juniorimportance: should knowfreq 35%

answer

  1. For library authors, not app code
  2. explicitApi() / -Xexplicit-api=strict
  3. Forces visibility keyword + explicit return type
  4. Only public/protected affected
  5. Default public is the hazard it prevents

basics

~10 s

It's a compiler mode for libraries. It forces you to write the visibility keyword (like public) and the return type on everything your library exposes, so nothing leaks out by accident.

solid answer

~40 s

Explicit API mode is a Kotlin compiler feature (enabled via explicitApi() in the build script or the -Xexplicit-api=strict/warning flag) aimed at library authors. Kotlin normally defaults declarations to public and infers return types, which is convenient for app code but risky for a published API. Explicit API mode reports an error (strict) or warning (warning) when a public/protected member omits an explicit visibility modifier, or when a public function/property relies on an inferred return type instead of a declared one. This makes every exposed symbol intentional: you must consciously write public or downgrade to internal/private, and you must spell out return types. It does not affect internal or private declarations. The goal is preventing accidental API exposure and making the public surface stable and reviewable.

code

kotlin · 7 lines
kotlin
kotlin {
    explicitApi() // strict: build fails on missing visibility/return types
}

// must now be written explicitly:
public fun parse(input: String): Result = TODO()
internal fun helper(): Int = 42 // hidden from API on purpose

go deeper

for a junior

Knows it forces you to write public and the return type, and that it's for libraries.

for a middle

Names explicitApi() and -Xexplicit-api=strict, and that only public/protected are affected.

for a senior

Explains strict vs warning, the accidental-exposure motivation, and that it doesn't replace binary compat tracking.

for a principal

Frames it as one layer of API governance alongside BCV, deprecation policy, and review, and weighs adoption cost on a large codebase.

## What it is **Explicit API mode** is a Kotlin compiler mode intended for **library authors** (not application code). In ordinary Kotlin, a declaration with no visibility modifier defaults to **public**, and the compiler **infers** the return type of functions and properties. That convenience becomes a hazard when you publish a library: you can accidentally make something public, or change an inferred return type without noticing, breaking consumers. ## The two things it enforces When enabled, the compiler flags an issue (error or warning) in two situations for **public and protected** declarations: - **Missing explicit visibility** — you must write `public` (or `internal`/`private`) rather than relying on the default `public`. - **Missing explicit return type** — a public function or property must declare its return type instead of relying on type inference. It does **not** touch `internal`, `private`, or local declarations, and it does not force visibility on overrides or on primary-constructor properties in some cases where inference is unambiguous. ## How to turn it on ```kotlin // build.gradle.kts kotlin { explicitApi() // == strict, fails the build // or: explicitApiWarning() // warnings only } ``` Equivalent compiler flags: - `-Xexplicit-api=strict` — reports **errors** (build fails). - `-Xexplicit-api=warning` — reports **warnings** only. ## Before / after ```kotlin // Without explicit API mode (defaults to public, return type inferred) fun greet(name: String) = "Hi, $name" // With explicit API mode you must write: public fun greet(name: String): String = "Hi, $name" // ...or hide it: internal fun greet(name: String): String = "Hi, $name" ``` ## Why it matters It makes the **public surface intentional and reviewable**: every exposed symbol carries a visibility keyword you chose, and every public signature has a stable, declared type. This complements (but does not replace) **Binary Compatibility Validator**, which tracks the actual API dump across versions.

  • Does explicit API mode affect private functions?
    No. It only flags public and protected declarations; private, internal, and local declarations are untouched.
  • What is the difference between explicitApi() and explicitApiWarning()?
    explicitApi() is strict — violations are compile errors that fail the build. explicitApiWarning() reports the same issues as warnings only.

Like a customs form: nothing crosses your library's border unless you've explicitly declared it.

saying these in an interview costs you the question

  • Thinking it changes the default visibility from public to private
  • Claiming it affects internal/private declarations
  • Saying it enforces KDoc/documentation
  • Believing it's meant for ordinary application modules
  • Confusing it with Binary Compatibility Validator's API dumps

context

resolving links…