Gradle Implementation vs API configuration

Gradle compile keyword was deprecated in favor of the api and implementation keywords to configure dependencies.

Using api is the equivalent of using the deprecated compile, so if you replace all compile with api everything will works as always.

To understand the implementation keyword consider the following example.

EXAMPLE

Suppose you have a library called MyLibrary that internally uses another library called InternalLibrary. Something like this:

// 'InternalLibrary' module
public class InternalLibrary {
    public static String giveMeAString(){
        return "hello";
    }
}

// 'MyLibrary' module
public class MyLibrary {
    public String myString(){
        return InternalLibrary.giveMeAString();
    }
}

Suppose the MyLibrary build.gradle uses api configuration in dependencies{} like this:

dependencies {
    api project(':InternalLibrary')
}

You want to use MyLibrary in your code so in your app's build.gradle you add this dependency:

dependencies {
    implementation project(':MyLibrary')
}

Using the api configuration (or deprecated compile) you can access InternalLibrary in your application code:

// Access 'MyLibrary' (granted)
MyLibrary myLib = new MyLibrary();
System.out.println(myLib.myString());

// Can ALSO access the internal library too (but you shouldn't)
System.out.println(InternalLibrary.giveMeAString());

In this way the module MyLibrary is potentially "leaking" the internal implementation of something. You shouldn't (be able to) use that because it's not directly imported by you.

The implementation configuration was introduced to prevent this. So now if you use implementation instead of api in MyLibrary:

dependencies {
    implementation project(':InternalLibrary')
}

you won't be able to call InternalLibrary.giveMeAString() in your app code anymore.

This sort of boxing strategy allows Android Gradle plugin to know that if you edit something in InternalLibrary, it must only trigger the recompilation of MyLibrary and not the recompilation of your entire app, because you don't have access to InternalLibrary.

When you have a lot of nested dependencies this mechanism can speed up the build a lot. (Watch the video linked at the end for a full understanding of this)

CONCLUSIONS

• When you switch to the new Android Gradle plugin 3.X.X, you should replace all your compile with the implementation keyword *(1). Then try to compile and test your app. If everything it's ok leave the code as is, if you have problems you probably have something wrong with your dependencies or you used something that now is private and not more accessible. *Suggestion by Android Gradle plugin engineer Jerome Dochez (1))

• If you are a library mantainer you should use api for every dependency which is needed for the public API of your library, while use implementation for test dependencies or dependencies which must not be used by the final users.

Useful article Showcasing the difference between implementation and api

REFERENCES (This is the same video splitted up for time saving)

Google I/O 2017 - How speed up Gradle builds (FULL VIDEO)

Google I/O 2017 - How speed up Gradle builds (NEW GRADLE PLUGIN 3.0.0 PART ONLY)

Google I/O 2017 - How speed up Gradle builds (reference to 1*)

Android documentation

I like to think about an api dependency as public (seen by other modules) while implementation dependency as private (only seen by this module).

Note, that unlike public/private variables and methods, api/implementation dependencies are not enforced by the runtime. This is merely a build-time optimization, that allows Gradle to know which modules it needs to recompile when one of the dependencies changes its API.

Consider you have app module which uses lib1 as a library and lib1 uses lib2 as a library. Something like this: app -> lib1 -> lib2.

Now when using api lib2 in lib1, then app can see lib2 codes when using: api lib1 or implementation lib1 in the app module.

BUT when using implementation lib2 in lib1, then app can not see the lib2 codes.

From gradle documentation:

Let’s have a look at a very simple build script for a JVM-based project.

plugins {
    id 'java-library'
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.hibernate:hibernate-core:3.6.7.Final'
    api 'com.google.guava:guava:23.0'
    testImplementation 'junit:junit:4.+'
}

implementation

The dependencies required to compile the production source of the project which are not part of the API exposed by the project. For example the project uses Hibernate for its internal persistence layer implementation.

api

The dependencies required to compile the production source of the project which are part of the API exposed by the project. For example the project uses Guava and exposes public interfaces with Guava classes in their method signatures.

Answers from @matpag and @dev-bmax are clear enough to make people understand different usages between implementation and api. I just want to make an extra explaination from another angle, hopes to help for peoples that have the same question.

I created two projects for testing :

• project A as a java library project named 'frameworks-web-gradle-plugin' depends on 'org.springframework.boot:spring-boot-gradle-plugin:1.5.20.RELEASE'
• project B depends on project A by implementation 'com.example.frameworks.gradle:frameworks-web-gradle-plugin:0.0.1-SNAPSHOT'

The dependencies hierarchy descripted above looks like:

[project-b] -> [project-a] -> [spring-boot-gradle-plugin]

Then I tested following scenarios:

1. Make project A depends on 'org.springframework.boot:spring-boot-gradle-plugin:1.5.20.RELEASE' by implementation .

   Run gradle dependencies command in a terminal in poject B root dir，with following screenshot of output we can see that 'spring-boot-gradle-plugin' appears in runtimeClasspath dependencies tree, but not in compileClasspath's, I think that's exactly why we can't make use of library that declared using implementation, it just won't through compilation.

   

2. Make project A depends on 'org.springframework.boot:spring-boot-gradle-plugin:1.5.20.RELEASE' by api

   Run gradle dependencies command in a terminal in poject B root dir again. Now 'spring-boot-gradle-plugin' appears both in compileClasspath and runtimeClasspath dependencies tree.

   

A significant difference I noticed is that the dependency in producer/library project declared in implementation way won't appear in compileClasspath of consumer projects, so that we can't make use of corresponding lib in the consumer projects.