== Why is this an issue?

The public API of a framework, plugin, or library is the way its provider intended it to be used.
API stability and compatibility (within the same major version number) of a library are guaranteed only for its public API.

Internal APIs are mere implementation details and are prone to breaking changes as the implementation of the library changes.
No guarantees are being made about them. Therefore, users should not use internal APIs, even when visible.

=== What is the potential impact?

==== Code Stability

If not fixed, your code might break when the library is upgraded to a new version, even if only the minor version number or the patch number changes.

== How to fix it

Replace internal API usage with the public API designed for your use case.
This may imply a refactoring of the affected code if no one-to-one replacement is available in the public API.
If a specific functionality is required, copying the required parts of the implementation into your code may even be better than using the internal API.

=== Code examples

==== Noncompliant code example

[source,kotlin,diff-id=1,diff-type=noncompliant]
----
if (org.gradle.internal.os.OperatingSystem.current().isWindows) { // Noncompliant, OperatingSystem is part of Gradle internal API
    // ...
}
----

==== Compliant solution

[source,kotlin,diff-id=1,diff-type=compliant]
----
if (System.getProperty("os.name").toLowerCase().contains("windows")) { // Compliant
    // ...
}
----

== Resources

=== Documentation

* https://docs.gradle.org/current/userguide/authoring_maintainable_build_scripts.html#sec:avoiding_gradle_internal_apis[Gradle Documentation - Avoid using internal Gradle APIs]
* https://github.com/liutikas/gradle-best-practices#dont-use-internal-apis[Best Practices when using Gradle - Don't use internal APIs (Liutikas)]
