APIs: How Hard Can They Be?

Talk by Aurimas Liutikas and Alan Viverette at KotlinConf 2025

Transcript

1. APIs: How Hard Can They Be? Alan Viverette Aurimas Liutikas reddit.com/u/alanviverette androiddev.social/@aurimas
2. Who are we? Alan 14 years at Google 12 years on Android 10 years on Android API Council Aurimas 13 years at Google 10 years on Android 8 years on Android API Council
3. Why do we care about APIs?
5. Different policies for different clients
6. For all developers Public APIs • Public documentation • Strong compatibility guarantees • High quality bar
7. For early adopters Experimental APIs • Public documentation • No compatibility guarantees • Intended to become stable public APIs
8. For internal use only Restricted APIs • No public documentation • Minimal compatibility guarantees • Similar to private or internal
9. Restricted APIs room-testing v1.0.0 room-common v1.0.0 fun implDetail() ✅
10. Restricted APIs room-testing v1.0.0 room-common v1.0.0 fun implDetail() room-testing v1.1.0 room-common v1.1.0 fun renamedFun() 😢
11. Restricted APIs room-testing v1.0.0 room-common v1.0.0 fun implDetail() room-testing v1.1.0 room-common v1.1.0 fun renamedFun() ✅ ✅
12. What makes an API “goodˮ?
13. Familiar naming API Principle #1 Consistency Shared concepts
14. Documentation API Principle #2 Usability Language conventions Sample code
15. API Principle #3 Compatibility Contract 🤝 Source ✍ Binary 🧱
16. • Does this still work as documented? • Does a comprehensive set of tests still pass? Contract compatibility
17. Contract compatibility /** * Returns the sum of [a] and [b]. */ fun add(a: Int, b: Int) = a + b
18. Contract compatibility /** * Returns the sum of [a] and [b]. */ fun add(a: Int, b: Int) = 0 🙁
19. Contract compatibility /** * Always returns zero. */ fun add(a: Int, b: Int) = 0 😦
20. API Principle #3 Compatibility Contract 🤝 Source ✍ Binary 🧱
21. • Does this require changing source code? Source compatibility
22. API Principle #3 Compatibility Contract 🤝 Source ✍ Binary 🧱
23. • Does this require re-compiling binaries? Binary compatibility
24. Binary compatibility /** * Returns the sum of [a] and [b]. */ fun add(a: Int, b: Int) = a + b
25. Binary compatibility /** * Returns the sum of [a] and [b]. */ fun add(a: Int, b: Int) = a + b
26. Binary compatibility // My app code val sum = add(first, second)
27. Binary compatibility // My library code val sum = add(first, second) com.myorg.mylibrary:1.1.0 release-v1.1.0.jar com.alanv.fancymath:2.0.0 depends on 🙄
28. Binary compatibility com.myorg.mylibrary:1.1.0 com.alanv.fancymath:2.0.0 My Application com.google.somelib:1.0.0 com.alanv.fancymath:1.0.0 😭
29. 󰺼 Examples of API breakages
30. Renaming a File
31. Renaming a File
32. javap (disassembler) Part of JDK .class → human-readable representation of bytecode instructions
33. Renaming a File (before) $ javap Example1Kt.class public final class org.example.Example1Kt { public static final void myMethod(); }
34. Renaming a File (after) $ javap Example1NewKt.class public final class org.example.Example1NewKt { public static final void myMethod(); }
35. Renaming a File $ javap Example1NewKt.class public final class org.example.Example1NewKt { public static final void myMethod(); } source compatibility binary compatibility contract compatibility Kotlin users ✅ 💥 💥 Java users 💥 💥 💥
36. Adding a Constructor
37. Adding a Constructor $ javap Example2.class public final class org.example.Example2 { public org.example.Example2(); }
38. Adding a Constructor $ javap Example2.class public final class org.example.Example2 { public org.example.Example2(java.lang.String); }
39. Adding a Constructor $ javap Example2.class public final class org.example.Example2 { public org.example.Example2(java.lang.String); } source compatibility binary compatibility contract compatibility Kotlin users 💥 💥 💥 Java users 💥 💥 💥
40. Adding a New Default Method
41. Adding a New Default Method source compatibility binary compatibility contract compatibility Kotlin users ❓ ✅ ❓ Java users ❓ ✅ ❓
42. Changing parameter type
43. Changing parameter type class User private constructor() { fun makeCall() { Example4().myMethod("Aurimas") } }
44. Changing parameter type $ javap -c User.class public final class org.example.user.User { public final void makeCall(); Code: ... 7: ldc #16 // String Aurimas 9: invokevirtual #20 // Method org/example/Example4.myMethod:(Ljava/lang/String;)V }
45. Changing parameter type $ javap -c User.class public final class org.example.user.User { public final void makeCall(); Code: ... 7: ldc #16 // String Aurimas 9: invokevirtual #20 // Method org/example/Example4.myMethod:(Ljava/lang/String;)V } source compatibility binary compatibility contract compatibility Kotlin users ✅ 💥 ✅ Java users ✅ 💥 ✅
46. 😫 Are you worried?
47. 😭 Real Life Example
52. 16 months later
54. What Went Wrong? APIs marked with @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP) APIs used cross library groups (androidx.room using androidx.sqlite) User upgraded androidx.sqlite without upgrading androidx.room
55. Preventing Regressions Added Android Lint check src/com/example/myapplication/test.kt:7: Error: LibraryCode.method2 can only be called from within the same library (lib) [RestrictedApiAndroidX]
56. Takeaway Be careful on what you consider your API surface
57. 😭 Real Life Example #2
58. Call to removeLast() public fun doThings(list: MutableList<String>) { list.removeLast() }
59. Added in JDK 21 package java.util; interface List<E> { default E removeLast() }
60. Kotlin-stdlib extension function package kotlin.collections public fun <T> MutableList<T>.removeLast(): T = if (isEmpty()) throw NoSuchElementException("List is empty.") else removeAt(lastIndex)
61. $ javap -c RemoveLastUser.class --release 17 7: invokestatic #28 // Method kotlin/collections/CollectionsKt.removeLast:(Ljava/util/List ;)Ljava/lang/Object; --release 21 7: invokeinterface #28, 1 // InterfaceMethod java/util/List.removeLast:()Ljava/lang/Object;
62. Android SDK API 33 and older ✅ It works using kotlin-stdlib!
63. Android SDK API 34
64. Android SDK API 34  API 34 device ✅ It works using java.util.List.removeLast()
65. Android SDK API 34  API 33 device 💥 Crash as java.util.List.removeLast() doesnʼt exist
66. Workaround import kotlin.collections.removeLast as removeLastKt public fun doThings(list: List<String>) { list.removeLastKt() }
67. Takeaway Be careful with extension functions for popular types you donʼt own
68. 🛠 Tooling and its benefits
69. Automate the tedious bits
70. Metalava • API management command-line tool • Apache 2.0 • Origins in Android OS project • Owned by Google
71. Metalava BCV Input source binary Supports JVM / Android ✅ ✅ Supports Kotlin Native ❌ ✅ Identity Comparison ✅ ✅ Compatibility Checks ✅ ❌ API linting ✅ ❌
72. Example Metalava Usage java -cp all/metalava.jar com.android.tools.metalava.Driver --format=v4 --source-path /path/to/resources:/path/to/kotlin --classpath /path/to/android.jar:/path/to/kotlin-stdlib-2.1.0.jar --api lib/build/current.txt
73. Example Metalava Usage java -cp all/metalava.jar com.android.tools.metalava.Driver --format=v4 --source-path /path/to/resources:/path/to/kotlin --classpath /path/to/android.jar:/path/to/kotlin-stdlib-2.1.0.jar --api lib/build/current.txt
74. package org.example class Example4 { fun myMethod(text: String) { } } // Signature format: 4.0 package org.example { public final class Example1 { ctor public Example1(); method public void myMethod(String text); } }
75. package org.example class Example4 { fun myMethod(text: String) { } } // Signature format: 4.0 package org.example { public final class Example1 { ctor public Example1(); method public void myMethod(String text); } }
76. Example Metalava Usage java -cp all/metalava.jar com.android.tools.metalava.Driver --format=v4 --source-path /path/to/resources:/path/to/kotlin --classpath /path/to/android.jar:/path/to/kotlin-stdlib-2.1.0.jar --check-compatibility:api:released lib/1.1.0.txt
78. api.txt:5: error: Removed method org.example.Example4.myMethod(String) RemovedMethod]
79. Binary Compatibility Validator BCV • API management command-line tool • Apache 2.0 • Owned by Jetbrains
80. Metalava BCV Input source binary Supports JVM / Android ✅ ✅ Supports Kotlin Native ❌ ✅ Identity Comparison ✅ ✅ Compatibility Checks ✅ ❌ API linting ✅ ❌
81. Example BCV Usage plugins { id("org.jetbrains.kotlinx.binary-compatibility-validator") version "0.17.0" }
82. ./gradlew apiDump public final class org/example/Example4 { public fun <init> ()V public final fun myMethod (Ljava/lang/String;)V }
83. ./gradlew apiCheck public final class org/example/Example4 { public fun <init> ()V - public final fun myMethod (Ljava/lang/String;)V + public final fun myMethod (Ljava/lang/CharSequence;)V }
84. BCV • Support for compatibility comparing for Kotlin native (klib) targets • Different rules than JVM • Rules are still evolving • Not published (plan to upstream)
85. Life of a Jetpack API
86. Local development • Write and review design doc • Implement changes • Validate APIs • Upload commit with Relnote: stanza Local development • Write and review design doc • Implement changes • Validate APIs • Upload commit with Relnote: stanza Code review • Validate APIs as a presubmit check • Review for API2 approval bit • Resolve feedback • Merge commit
87. Code review • Validate APIs as a presubmit check • Review for API2 approval bit • Resolve feedback • Merge commit Local development • Write and review design doc • Implement changes • Validate APIs • Upload commit with Relnote: stanza Local development • Write and review design doc • Implement changes • Validate APIs • Upload commit with Relnote: stanza Code review • Validate APIs as a presubmit check • Review for API2 approval bit • Resolve feedback • Merge commit Post-merge • CI files review bug • Spot-check APIs in group review • Respond to feedback • Schedule release
88. Post-merge • CI files review bug • Spot-check APIs in group review • Respond to feedback • Schedule release Local development • Write and review design doc • Implement changes • Validate APIs • Upload commit with Relnote: stanza Code review • Validate APIs as a presubmit check • Review for API2 approval bit • Resolve feedback • Merge commit Release • Validate all APIs have approved • Review release notes • Publish API docs and release notes
89. Release • Validate all APIs have approved • Review release notes • Publish API docs and release notes Local development • Write and review design doc • Implement changes • Validate APIs • Upload commit with Relnote: stanza Code review • Validate APIs as a presubmit check • Review for API2 approval bit • Resolve feedback • Merge commit Post-merge • CI files review bug • Spot-check APIs in group review • Respond to feedback • Schedule release
90. Lessons from Jetpack
91. Manual review scales linearly. Please rename this to setOnClickListener No, this should addClickCallback What about setOnClickCallback? Hey, I’m ready for review! R
92. Developers donʼt like to commit. com.myorg + mylibrary + 1.0.0-alpha01 + 1.0.0-alpha02 + 1.0.0-alpha03 + 1.0.0-alpha04 + 1.0.0-alpha05 + 1.0.0-alpha06 + 1.0.0-alpha07 + 1.0.0-alpha08 + 1.0.0-alpha09 + 1.0.0-alpha10 + 1.0.0-alpha11
93. Best practices change over time.
94. Summary: Why you should track your APIs?
95. Machines are great at tedious tasks, humans are not
96. Allows building process around API changes
97. More focus on good API design
98. Thank You!
99. Donʼt Forget to Vote Links