androidgradledependenciesimplementation

Gradle Implementation vs API configuration


I'm trying to figure out what is the difference between api and implementation configuration while building my dependencies.

In the documentation, it says that implementation has better build time, but, seeing this comment in a similar question I got to wonder if is it true.

I'm not an expert in Gradle. I've read the documentation already but I was wondering about an easy-to-understand explanation.


Solution

  • 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

    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