OS Versions and API Levels

Android has come a long way since the early beta releases from late 2007. Each new Android OS version adds more capabilities to the platform and more things that developers can do to exploit those capabilities.

Moreover, the core Android development team tries very hard to ensure forwards and backwards compatibility. An app you write today should work unchanged on future versions of Android (forwards compatibility), albeit perhaps missing some features or working in some sort of “compatibility mode”. And there are techniques for creating apps that will work both on the latest and on previous versions of Android (backwards compatibility).

To help us keep track of all the different OS versions that matter to us as developers, Android has API levels. A new API level is defined when an Android version ships that contains changes that affect developers. When you create an emulator AVD to test your app, you will indicate what API level that emulator should emulate. When you distribute your app, you will indicate the oldest API level your app supports, so the app is not installed on older devices.

We started with API Level 1 and Android 1.0… but that was a long time ago. Nowadays, the focus tends to be on newer versions of Android and corresponding higher API levels. Here, though, Android gets a bit complicated, as there are a lot of different versions of Android being used today.

Google used to publish up-to-date version information on its dashboards page, but they abandoned that a while ago. Instead, they rely on you creating a new project and looking at a version distribution chart available from the new project wizard.

Or, you could just look at the copy of that chart shown here:

The chart shows the various Android versions, their API level numbers, and the “cumulative distribution”. The cumulative distribution shows you what percentage of the Android device ecosystem you can reach if your minSdkVersion is set to that particular API level. Their numbers are based on devices using the Play Store and therefore will miss many devices that are based on other distribution channels.

This book focuses on Android 5.0 (API Level 21) and higher. There are ways to support older devices than that, but supporting older than Android 4.4 (API Level 19) gets complicated, so this book skips that to help keep the explanations simple.

At the time that this chapter was last updated, the latest production version of Android was 12 (API Level 31). This is not shown in the chart, because Google appears to have forgotten to update the chart in over a year.

Beyond the latest production version, from time to time we are given “developer previews” of an upcoming version of Android. These are not good choices for new Android developers to worry about, but experienced developers may be interested in testing on pre-release Android versions and trying to use upcoming features. For example, in February 2021, Google announced “Android S” and released the first developer preview of what became Android 12.