Android Versions and API Levels

Overview

Android versions are identified by both release names and internal API levels. An API level is an integer that uniquely represents each version of the Android platform. When developing Android applications, understanding the relationship between Android releases and API levels is essential for compatibility, feature availability, and runtime behavior.

This document explains how Android versions and API levels correlate, how to use them in development, and how to target specific platform capabilities.

What Is an API Level?

An API (Application Programming Interface) level is a unique integer assigned to a particular version of the Android framework. It represents the set of APIs available in that version. When you target or compile against a specific API level, you are indicating which framework features your app can use and which minimum platform it supports.

In Android development:

• compileSdkVersion determines which APIs you compile against
• minSdkVersion sets the lowest API level your app supports
• targetSdkVersion indicates the API level your app is designed for

These settings are configured in the app’s build.gradle file.

How Android Versions Map to API Levels

Each major Android platform release corresponds to a specific API level (or levels). Below is a concise mapping that developers reference when determining compatibility and feature support:

API levels allow the Android framework to maintain backward compatibility while enabling new features in later versions.

Setting API Levels in Android Projects

When building an Android app, the following attributes in build.gradle control how the app behaves across different Android versions:

android {
    compileSdkVersion 33
    defaultConfig {
        minSdkVersion 21
        targetSdkVersion 33
    }
}

Key Fields

• compileSdkVersion:
  The API level used to compile your app. Should generally be set to the latest stable API level to use the newest APIs and tools.
• minSdkVersion:
  The lowest API level on which your app can run. Devices with lower API levels will not install the app.
• targetSdkVersion:
  Indicates the API level your app is optimized for. It signals to the platform that your app has been tested against that level’s behavior changes.

Using Conditional Logic for API Compatibility

Android provides runtime checks for API-specific features to maintain compatibility with older devices:

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
    // Use a Marshmallow (API 23) feature
} else {
    // Fallback behavior for older versions
}

Using Build.VERSION.SDK_INT ensures that code paths only execute on devices that support the corresponding APIs.

Why API Levels Matter

Feature Detection

Some APIs only exist in newer Android versions. Explicit API level checks prevent your app from crashing on older devices.

Backward Compatibility

Google maintains the Android Support libraries (now AndroidX) to backport many features, but some capabilities still depend on the platform version and corresponding API level.

App Distribution

Google Play uses API levels to determine device eligibility and feature availability. Setting an appropriate minimum and target SDK improves device coverage without sacrificing modern features.

Best Practices for API Level Management

• Set compileSdkVersion to the latest stable API to access new tools.
• Incrementally raise targetSdkVersion over time to adopt platform behavior changes.
• Set minSdkVersion as low as feasible, balancing device coverage with development complexity.
• Use AndroidX libraries to maximize backward compatibility.
• Guard API-specific code with proper version checks.