Recognizing gradle api vs implementation examples (i.e. When to use either?)

Question

I'm reading this Gradle documentation on how to recognize dependencies as either API or implementation.

I've checked this StackOverflow answer but it doesn't quite address this: Gradle Implementation vs API configuration

It would be helpful to have an example of each of these so that we know when to use api or implementation. Below is the documentation (linked above), along with examples that I've added.

It would help me learn if you could take a look at these examples and let me know if they're accurate. If not, please do add your own examples:

So when should you use the api configuration? An API dependency is one that contains at least one type that is exposed in the library binary interface, often referred to as its ABI (Application Binary Interface). This includes, but is not limited to:

• types used in super classes or interfaces

class MyClass implements MyInterface {
   @Override
   void doSomething(MyObject myObj) {
     //...
   }
}

interface MyInterface {
  void doSomething(MyObject myObj);
}

dependencies {
  api project(':moduleThatContainsMyObject')
}

• types used in public method parameters, including generic parameter types (where public is something that is visible to compilers. I.e. , public, protected and package private members in the Java world)

public void doSomething(MyObject obj) {
  //...
}

dependencies {
  api project(':moduleThatContainsMyObject')
}

• types used in public fields

class MyClass {
  public MyObject myObj;
}

dependencies {
  api project(':moduleThatContainsMyObject')
}

public annotation types

@Target(METHOD)
@Retention(RUNTIME)
public @interface MyAnnotation

dependencies {
  api project(':moduleThatContainsMyAnnotation')
}

By contrast, any type that is used in the following list is irrelevant to the ABI, and therefore should be declared as an implementation dependency:

• types exclusively used in method bodies

public void doSomething() {
  MyObject myObj = new MyObject();
}

dependencies {
  implementation project(':moduleThatContainsMyObject')
}

• types exclusively used in private members

class MyClass {
  private MyObject myObj;
}

dependencies {
  implementation project(':moduleThatContainsMyObject')
}

• types exclusively found in internal classes (future versions of Gradle will let you declare which packages belong to the public API)

Recognizing gradle api vs implementation examples (i.e. When to use either?)

0 Answers0