API Level: wat het is, API-versies en targetSdk

Wat is API Level Android?

API Level Android is een integer-identificatie die wordt toegewezen aan elke openbare release van de Android Framework API. De eerste release Android 1.0 had API Level 1, Android 1.5 — API Level 3, Android 2.2 — API Level 8, Android 4.0 — API Level 14, Android 8.0 — API Level 26, Android 12 — API Level 31, Android 14 — API Level 34, Android 15 — API Level 35, Android 16 (2025) — API Level 36. Elk nieuw API Level kan nieuwe klassen, methoden, constanten, machtigingen toevoegen en het gedrag van bestaande wijzigen.

API Level neemt niet strikt met 1 toe bij elke release. Bijvoorbeeld Android 4.4W (Wear) heeft API 20, terwijl Android 5.0 — API 21 heeft. Hiaten hebben te maken met interne iteraties en Wear OS-apparaten. Voor de ontwikkelaar is het belangrijk om niet de versienaam (KitKat, Lollipop, Tiramisu) te kennen, maar het API Level — dit wordt in de code gebruikt voor compatibiliteitscontroles.

Het belangrijkste doel van API Level is achterwaartse compatibiliteit. Een tegen API 34 gecompileerde app kan werken op apparaten met API 34 en lager (als het geen nieuwe API's zonder controle gebruikt). Android Runtime (ART) controleert API-aanroepen op systeemniveau en past gedragsveranderingen toe op basis van de targetSdkVersion van de app.

Hoe Android API Level verwerkt

Bij het installeren van een app controleert PackageManager of het API Level van het apparaat >= minSdkVersion uit AndroidManifest.xml is. Als niet aan de voorwaarde wordt voldaan — wordt de installatie geblokkeerd met het bericht "App not installed". Tijdens runtime controleert Android Runtime API-aanroepen die een hoger API Level vereisen en genereert NoSuchMethodError of UnsatisfiedLinkError als de methode niet bestaat in de huidige versie.

minSdk, targetSdk, compileSdk: verschillen en rol van elke parameter

In het build.gradle-bestand (Module: app) specificeert de ontwikkelaar drie API Level-parameters: minSdkVersion, targetSdkVersion en compileSdkVersion. Ze verwarren is een van de meest voorkomende fouten van beginnende Android-ontwikkelaars. Elke parameter is verantwoordelijk voor een ander aspect van compatibiliteit en hun waarden moeten consistent zijn.

minSdkVersion

minSdkVersion is het minimale API Level waarop de app kan worden geïnstalleerd en uitgevoerd. Apparaten met een API Level onder minSdk zien de app niet in Google Play en kunnen deze niet installeren. De waarde wordt gekozen op basis van de doelgroep: minSdk 21 (Android 5.0) dekt 97% van de apparaten, minSdk 26 (Android 8.0) — ongeveer 85%, minSdk 31 (Android 12) — ongeveer 55% (gegevens van Android Studio Distribution Dashboard, 2026). Hoe lager minSdk, hoe groter de dekking, maar hoe meer achterwaartse compatibiliteitscode nodig is.

targetSdkVersion

targetSdkVersion is het API Level waartegen de app is getest. Android gebruikt targetSdk om gedragsveranderingen toe te passen: als de app targetSdk 33 specificeert, activeert het systeem alle gedragsveranderingen die in API 33 zijn geïntroduceerd. Als targetSdk 31 is, past het systeem API 32-33 wijzigingen niet toe, waardoor compatibiliteit met oud gedrag behouden blijft. Dit is de belangrijkste parameter voor beveiliging: Google Play vereist targetSdk niet ouder dan 1 jaar vanaf het huidige API Level.

compileSdkVersion

compileSdkVersion is de Android SDK-versie waartegen de code wordt gecompileerd. Het bepaalt welke API's beschikbaar zijn tijdens compilatie. compileSdk moet >= targetSdk zijn en idealiter gelijk aan het laatste stabiele API Level. Verhogen van compileSdk heeft geen invloed op runtime-gedrag — alleen op de beschikbaarheid van nieuwe API's voor de compiler. Na het verhogen van compileSdk moet de code worden gecontroleerd op verouderde API's en nieuwe machtigingsvereisten.

// build.gradle.kts — voorbeeld van API Level-configuratie
plugins {
    id("com.android.application") version "8.7.0"
    id("org.jetbrains.kotlin.android") version "2.1.0"
}

android {
    namespace = "com.example.myapp"
    compileSdk = 36  // Android 16

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26      // Android 8.0
        targetSdk = 36    // Android 16
        versionCode = 1
        versionName = "1.0.0"
    }

    buildTypes {
        release {
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    kotlinOptions {
        jvmTarget = "17"
    }
}

dependencies {
    implementation("androidx.core:core-ktx:1.15.0")
    implementation("androidx.appcompat:appcompat:1.7.0")
    implementation("androidx.activity:activity-ktx:1.9.3")
}

In het build.gradle.kts-voorbeeld is compileSdk = 36 (nieuwste op het moment van schrijven), targetSdk = 36, minSdk = 26 (Android 8.0). compileSdk 36 geeft toegang tot alle Android 16 API's. targetSdk 36 activeert alle Android 16 gedragsveranderingen. minSdk 26 dekt ~85% van de apparaten. AndroidX Activity KTX en AppCompat bieden achterwaartse compatibiliteit voor fragmenten en thema's.

AndroidManifest.xml

De parameters minSdk en targetSdk kunnen ook worden gespecificeerd in AndroidManifest.xml, maar moderne projecten gebruiken build.gradle — waarden van Gradle overschrijven het manifest. In het manifest kan het nuttig zijn om te specificeren voor bibliotheken en modules die geen Gradle-buildconfiguratie gebruiken.

Gedragsveranderingen: hoe targetSdk het app-gedrag beïnvloedt

Gedragsveranderingen zijn wijzigingen in de werking van het Android-systeem die alleen worden toegepast op apps met targetSdk >= een bepaald API Level. Elke nieuwe Android-release introduceert gedragsveranderingen die bestaande apps kunnen breken als ze niet worden bijgewerkt. Dit is een belangrijk beveiligingsmechanisme van Android: oude apps blijven werken zoals voorheen, nieuwe volgen de huidige regels.

Belangrijkste gedragsveranderingen per versie

Android 10 (API 29) — Scoped Storage: apps met targetSdk 29+ hebben geen directe toegang tot het gedeelde bestandssysteem, alleen via MediaStore, SAF of eigen opslag. Android 11 (API 30) — Package Visibility: pakketfilter, apps zien alleen geïnstalleerde pakketten waarmee ze interacteren. Android 12 (API 31) — Foreground Service Notification: alle voorgrondservices moeten binnen 10 seconden na start een melding tonen. Android 13 (API 33) — POST_NOTIFICATIONS: runtime-machtiging voor pushmeldingen. Android 14 (API 34) — Foreground Service Types: verplichte declaratie van het voorgrondservicetype in het manifest.

// Afhandeling van Android 13 (API 33) gedragsveranderingen: POST_NOTIFICATIONS
import android.Manifest
import android.content.pm.PackageManager
import android.os.Build
import androidx.activity.result.contract.ActivityResultContracts
import androidx.core.content.ContextCompat

class NotificationHelper {

    fun requestNotificationPermission(activity: MainActivity) {
        // POST_NOTIFICATIONS-machtiging werkt alleen met API 33+
        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
            return  // Onder API 33 is geen machtiging vereist
        }

        when {
            ContextCompat.checkSelfPermission(
                activity,
                Manifest.permission.POST_NOTIFICATIONS
            ) == PackageManager.PERMISSION_GRANTED -> {
                // Machtiging al verleend, meldingen kunnen worden verzonden
                showNotification(activity)
            }

            activity.shouldShowRequestPermissionRationale(
                Manifest.permission.POST_NOTIFICATIONS
            ) -> {
                // Toon uitleg waarom de machtiging nodig is
                activity.showRationale()
            }

            else -> {
                // Vraag machtiging aan
                activity.requestPermissionLauncher.launch(
                    Manifest.permission.POST_NOTIFICATIONS
                )
            }
        }
    }

    private fun showNotification(context: Context) {
        // Maak en toon melding
        val notification = android.app.Notification.Builder(context, "default_channel")
            .setSmallIcon(android.R.drawable.ic_dialog_info)
            .setContentTitle("Melding")
            .setContentText("Nieuw bericht")
            .build()
        val manager = context.getSystemService(Context.NOTIFICATION_SERVICE)
            as android.app.NotificationManager
        manager.notify(1, notification)
    }
}

// Registreer requestPermissionLauncher in Activity
class MainActivity : ComponentActivity() {
    val requestPermissionLauncher = registerForActivityResult(
        ActivityResultContracts.RequestPermission()
    ) { isGranted: Boolean ->
        if (isGranted) {
            // Machtiging verleend
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
    }
}

Voorbeeld van het afhandelen van POST_NOTIFICATIONS in Kotlin: controleer Build.VERSION.SDK_INT >= TIRAMISU, vraag runtime-machtiging aan via ActivityResultContracts.RequestPermission, verwerk het resultaat in een callback. Zonder deze machtiging kan een app met targetSdk 33+ geen pushmeldingen tonen. Onder API 33 is geen machtiging vereist — de controlecode voorkomt het aanroepen van niet-beschikbare API's.

Scoped Storage (Android 10+)

Scoped Storage is een van de belangrijkste gedragsveranderingen. Vanaf API 29 (targetSdk 29+) kan de app geen directe bestandstoegang krijgen tot de mappen Pictures, Downloads, Music en Documents. In plaats daarvan wordt MediaStore gebruikt voor media, SAF (Storage Access Framework) voor willekeurige bestanden en getExternalFilesDir() voor eigen opslag. De uitzondering zijn apps met de machtiging MANAGE_EXTERNAL_STORAGE, die goedkeuring van Google Play vereist.

Google Play-vereisten voor API Level en targetSdk

Google Play stelt verplichte targetSdkVersion-vereisten voor het publiceren van apps. Sinds augustus 2024 vereist Google Play targetSdkVersion >= API 33 (Android 13). Elk jaar stijgt de drempel: nieuwe apps en updates moeten targetSdk specificeren niet ouder dan 1 jaar vanaf het huidige hoofd-API Level. Overtreding van de vereiste leidt tot blokkering van publicatie en verwijdering van de app uit de winkel.

Waarom Google Play de vereisten aanscherpt

De belangrijkste reden is beveiliging. Elk nieuw Android API Level introduceert gedragsveranderingen die aanvalsvectoren afsluiten: Scoped Storage (API 29) voorkomt bestandsdiefstal, POST_NOTIFICATIONS (API 33) beschermt tegen spam-meldingen, Foreground Service Types (API 34) beperkt verborgen achtergrondservices. Apps met een laag targetSdk krijgen deze bescherming niet en worden een bedreiging voor gebruikers. Google Play kan verouderde apps op moderne apparaten niet toestaan.

Controle van naleving van vereisten

Google Play Console controleert targetSdkVersion bij het uploaden van APK/AAB. Als targetSdk onder de vereiste ligt — blokkeert de console de publicatie met het bericht: "Your app currently targets API level X and must target at least API level Y". De ontwikkelaar moet build.gradle bijwerken, de app opnieuw compileren, gedragsveranderingen testen en opnieuw uploaden. AAB-formaat wordt aanbevolen voor alle nieuwe publicaties (verplicht sinds augustus 2021).

API Level in code controleren: Build.VERSION.SDK_INT

Build.VERSION.SDK_INT is een statische integer-constante die het API Level bevat van het apparaat waarop de app wordt uitgevoerd. Het is het primaire hulpmiddel voor runtime Android-versiecontroles. Build.VERSION_CODES bevat benoemde constanten voor elk API Level: VERSION_CODES.TIRAMISU (33), VERSION_CODES.UPSIDE_DOWN_CAKE (34), VERSION_CODES.VANILLA_ICE_CREAM (35). Vergelijking via if (SDK_INT >= VERSION_CODES.TIRAMISU) is het standaardpatroon.

// Voorbeelden van API Level-controle in Android-code
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.drawable.AdaptiveIconDrawable

class ApiLevelHelper {

    // 1. Basis API Level-controle
    fun isAtLeastTiramisu(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU  // 33
    }

    // 2. Adaptieve API-aanroep met controle
    fun getAdaptiveIcon(drawable: android.graphics.drawable.Drawable):
            android.graphics.drawable.Drawable? {
        // AdaptiveIconDrawable is alleen beschikbaar met API 26 (Android 8)
        if (VERSION.SDK_INT >= VERSION_CODES.O) {
            return AdaptiveIconDrawable(drawable, null)
        }
        return drawable  // fallback voor oude apparaten
    }

    // 3. Controle van POST_NOTIFICATIONS-machtiging (alleen API 33+)
    fun canRequestNotificationPermission(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU
    }

    // 4. Selectie van afbeeldingsprovider op basis van API Level
    fun getImagePickerProvider(): String {
        return when {
            VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
                // API 34+ gebruikt PhotoPicker
                "photo_picker"
            }
            VERSION.SDK_INT >= VERSION_CODES.KITKAT -> {
                // API 19+ gebruikt Intent ACTION_OPEN_DOCUMENT
                "open_document"
            }
            else -> {
                // Legacy: ACTION_GET_CONTENT (alle versies)
                "get_content"
            }
        }
    }

    // 5. Java-stijl controle via @TargetApi (voor achterwaartse compatibiliteit)
    @Suppress("DEPRECATION")
    fun checkLegacyStorage(): Boolean {
        // Scoped Storage-gedrag hangt af van targetSdk, niet van SDK_INT
        return VERSION.SDK_INT < VERSION_CODES.Q  // Android 10
    }

    // 6. Build-informatie voor analyses
    fun getDeviceApiInfo(): Map<String, Any> {
        return mapOf(
            "sdk_int" to VERSION.SDK_INT,
            "release" to VERSION.RELEASE,
            "codename" to VERSION.CODENAME,
            "incremental" to VERSION.INCREMENTAL,
            "preview_sdk" to VERSION.PREVIEW_SDK_INT
        )
    }
}

// Testen
fun main() {
    val helper = ApiLevelHelper()
    println("API Level: ${VERSION.SDK_INT}")
    println("Is Tiramisu+: ${helper.isAtLeastTiramisu()}")
}

De klasse ApiLevelHelper demonstreert alle belangrijke API Level-controlepatronen: isAtLeastTiramisu met SDK_INT >= VERSION_CODES, getAdaptiveIcon met fallback voor oude versies, getImagePickerProvider met when-meervoudige vertakking, getDeviceApiInfo voor analyses. De belangrijkste regel is om geen nieuwe API's aan te roepen zonder SDK_INT te controleren, anders crasht de app met NoSuchMethodError op oude apparaten.

ANT (Android New API) en lint

Android Studio bevat de statische analyser lint, die waarschuwt voor het gebruik van API's boven minSdkVersion. Als een methode wordt aangeroepen zonder SDK_INT-controle, markeert lint dit als fout: "Call requires API level 34 (current min is 26)". Oplossingen: voeg @RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) toe aan de methode of een if-controle van SDK_INT. @TargetApi is een verouderde annotatie, @RequiresApi wordt aanbevolen.

Tabel van API Level en Android-versies

De API Level-tabel is een referentiehulpmiddel voor de ontwikkelaar. Door het API Level van het apparaat te kennen, kunt u de Android-versie en beschikbare functies bepalen. De tabel bevat alle belangrijke Android-releases van API Level 1 (2008) tot API Level 36 (2025). Codenamen (Cupcake, Donut, Tiramisu, VanillaIceCream) worden intern bij Google en in VERSION_CODES gebruikt.

Tabel: drempel-API Levels voor gedragsveranderingen

De volgende tabel toont de belangrijkste API Levels die gedragsveranderingen introduceren die achterwaartse compatibiliteit breken bij verhoging van targetSdk: