Explicit API Mode Kotlin
In Kotlin 1.4 a new compiler feature called explicit API mode was introduced, especially for library developers.
What is Explicit API Mode?
Kotlin compiler offers explicit API mode for library authors. In this mode, the compiler performs additional checks that help make the library’s API clearer and more consistent. It adds the following requirements for declarations exposed to the library’s public API:
- Visibility modifiers are required for declarations if the default visibility exposes them to the public API. This helps ensure that no declarations are exposed to the public API unintentionally.
- Explicit type specifications are required for properties and functions that are exposed to the public API. This guarantees that API users are aware of the types of API members they use.
Based on the configuration the compiler can either throw anerror or warning . For the ease of reading and reducing verbose code, few declarations are excluded from the above checks, namely
- primary constructors
- properties of data classes
- property getters and setters
overridemethods
Advantages of Explicit API Mode
- Being explicit about visibility modifiers avoids accidental exposure of internal APIs.
- With explicit with return types avoid accidental changes to the returns type which can cause a breaking change for the library consumers.
Example
If you look at the above API, the library developer can easily change the return type(accidentally) of the method getToken() without any error as the return type is implicitly derived by the compiler. This will break the code for the consuming application.
If the developer had explicitly declared the data-type in the method signature(as shown below) on changing the value from 1 to "1” would have given a compilation error and the developer would have noticed and taken a conscious decision and made a major version change or deprecated the API and added a new API.
The end goal here is somehow informing the consumers about the change in the return type and not surprising them.
How to enable Explicit API Mode?
For Kotlin Modules
To enable the explicit mode or compile your Kotlin module/library with explicit API mode add the below configuration to your module’s build.gradle file
For Android Library
To enable the explicit mode or compile your Android module/library with explicit API mode add the below configuration to your module’s build.gradle file
The above block kotlinOptions needs to be added inside the android block of your build.gradle file.
Explicit Mode in Action
Refer to the screenshots below to see how the error or warning shows in the IDE(these warnings/errors are shown in Android Studio)
Strict Mode
Warning
Explicit API mode for Application Modules
Though the documentation states that explicit API mode is for library developers it can be enabled for application modules as well if the need is and might be helpful in a monolith project, where each feature is a different package and is managed by separate teams.
To know more about the feature refer to the KEEP
