API Level: qué es, versiones de API y targetSdk

¿Qué es API Level Android?

API Level Android es un identificador entero asignado a cada versión pública de la API de Android Framework. El primer lanzamiento Android 1.0 tenía 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. Cada nuevo API Level puede añadir nuevas clases, métodos, constantes, permisos y modificar el comportamiento de los existentes.

El API Level no se incrementa estrictamente en 1 con cada versión. Por ejemplo, Android 4.4W (Wear) tiene API 20, mientras que Android 5.0 — API 21. Los saltos están relacionados con iteraciones internas y dispositivos Wear OS. Para el desarrollador es importante conocer no el nombre de la versión (KitKat, Lollipop, Tiramisu), sino su API Level — es lo que se usa en el código para las comprobaciones de compatibilidad.

El propósito clave de API Level es la compatibilidad hacia atrás. Una aplicación compilada contra API 34 puede funcionar en dispositivos con API 34 e inferiores (si no usa nuevas APIs sin verificación). Android Runtime (ART) comprueba las llamadas a la API a nivel del sistema y aplica cambios de comportamiento según el targetSdkVersion de la aplicación.

Cómo Android maneja el API Level

Al instalar una aplicación, PackageManager verifica que el API Level del dispositivo >= minSdkVersion del AndroidManifest.xml. Si no se cumple la condición — la instalación se bloquea con el mensaje "App not installed". Durante la ejecución, Android Runtime supervisa las llamadas a la API que requieren un API Level superior y genera NoSuchMethodError o UnsatisfiedLinkError si el método no está presente en la versión actual.

minSdk, targetSdk, compileSdk: diferencias y función de cada parámetro

En el archivo build.gradle (Module: app), el desarrollador especifica tres parámetros de API Level: minSdkVersion, targetSdkVersion y compileSdkVersion. Confundirlos es uno de los errores más comunes entre los desarrolladores principiantes de Android. Cada parámetro es responsable de un aspecto diferente de la compatibilidad, y sus valores deben ser coherentes.

minSdkVersion

minSdkVersion es el API Level mínimo en el que la aplicación puede instalarse y ejecutarse. Los dispositivos con API Level inferior a minSdk no ven la aplicación en Google Play y no pueden instalarla. El valor se elige en función del público objetivo: minSdk 21 (Android 5.0) cubre el 97% de los dispositivos, minSdk 26 (Android 8.0) — alrededor del 85%, minSdk 31 (Android 12) — alrededor del 55% (datos de Android Studio Distribution Dashboard, 2026). Cuanto menor sea el minSdk, mayor será la cobertura, pero más código de compatibilidad hacia atrás se necesitará.

targetSdkVersion

targetSdkVersion es el API Level contra el que se probó la aplicación. Android usa targetSdk para aplicar cambios de comportamiento: si la aplicación especifica targetSdk 33, el sistema activa todos los cambios de comportamiento introducidos en API 33. Si targetSdk es 31, el sistema no aplica los cambios de API 32-33, preservando la compatibilidad con el comportamiento anterior. Este es el parámetro más importante para la seguridad: Google Play exige targetSdk no mayor de 1 año desde el API Level actual.

compileSdkVersion

compileSdkVersion es la versión del SDK de Android contra la que se compila el código. Determina qué APIs están disponibles en tiempo de compilación. compileSdk debe ser >= targetSdk y, idealmente, igual al último API Level estable. Aumentar compileSdk no afecta al comportamiento en tiempo de ejecución — solo a la disponibilidad de nuevas APIs para el compilador. Después de aumentar compileSdk, hay que verificar el código en busca de APIs obsoletas y nuevos requisitos de permisos.

// build.gradle.kts — ejemplo de configuración de API Level
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")
}

En el ejemplo de build.gradle.kts, compileSdk = 36 (el último en el momento de escribir), targetSdk = 36, minSdk = 26 (Android 8.0). compileSdk 36 da acceso a todas las APIs de Android 16. targetSdk 36 activa todos los cambios de comportamiento de Android 16. minSdk 26 cubre ~85% de los dispositivos. AndroidX Activity KTX y AppCompat proporcionan compatibilidad hacia atrás para fragmentos y temas.

AndroidManifest.xml

Los parámetros minSdk y targetSdk también pueden especificarse en AndroidManifest.xml, pero los proyectos modernos usan build.gradle — los valores de Gradle sobrescriben el manifiesto. En el manifiesto, puede ser útil especificar para bibliotecas y módulos que no usan la configuración de compilación de Gradle.

Cambios de comportamiento: cómo targetSdk afecta al comportamiento de la aplicación

Los cambios de comportamiento son modificaciones en el funcionamiento del sistema Android que se aplican solo a aplicaciones con targetSdk >= un cierto API Level. Cada nueva versión de Android introduce cambios de comportamiento que pueden romper aplicaciones existentes si no se actualizan. Este es un mecanismo clave de seguridad de Android: las aplicaciones antiguas siguen funcionando como antes, las nuevas siguen las reglas actuales.

Principales cambios de comportamiento por versión

Android 10 (API 29) — Scoped Storage: las aplicaciones con targetSdk 29+ no tienen acceso directo al sistema de archivos compartido, solo a través de MediaStore, SAF o su propio almacenamiento. Android 11 (API 30) — Package Visibility: filtro de paquetes, las aplicaciones solo ven los paquetes instalados con los que interactúan. Android 12 (API 31) — Foreground Service Notification: todos los servicios en primer plano deben mostrar una notificación en los 10 segundos posteriores al inicio. Android 13 (API 33) — POST_NOTIFICATIONS: permiso en tiempo de ejecución para notificaciones push. Android 14 (API 34) — Foreground Service Types: declaración obligatoria del tipo de servicio en primer plano en el manifiesto.

// Manejo de cambios de comportamiento de Android 13 (API 33): 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) {
        // El permiso POST_NOTIFICATIONS solo funciona con API 33+
        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
            return  // Por debajo de API 33 no se requiere permiso
        }

        when {
            ContextCompat.checkSelfPermission(
                activity,
                Manifest.permission.POST_NOTIFICATIONS
            ) == PackageManager.PERMISSION_GRANTED -> {
                // Permiso ya concedido, se pueden enviar notificaciones
                showNotification(activity)
            }

            activity.shouldShowRequestPermissionRationale(
                Manifest.permission.POST_NOTIFICATIONS
            ) -> {
                // Mostrar explicación de por qué se necesita el permiso
                activity.showRationale()
            }

            else -> {
                // Solicitar permiso
                activity.requestPermissionLauncher.launch(
                    Manifest.permission.POST_NOTIFICATIONS
                )
            }
        }
    }

    private fun showNotification(context: Context) {
        // Crear y mostrar notificación
        val notification = android.app.Notification.Builder(context, "default_channel")
            .setSmallIcon(android.R.drawable.ic_dialog_info)
            .setContentTitle("Notificación")
            .setContentText("Mensaje nuevo")
            .build()
        val manager = context.getSystemService(Context.NOTIFICATION_SERVICE)
            as android.app.NotificationManager
        manager.notify(1, notification)
    }
}

// Registrar requestPermissionLauncher en Activity
class MainActivity : ComponentActivity() {
    val requestPermissionLauncher = registerForActivityResult(
        ActivityResultContracts.RequestPermission()
    ) { isGranted: Boolean ->
        if (isGranted) {
            // Permiso concedido
        }
    }

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

Ejemplo de manejo de POST_NOTIFICATIONS en Kotlin: verificar Build.VERSION.SDK_INT >= TIRAMISU, solicitar permiso en tiempo de ejecución mediante ActivityResultContracts.RequestPermission, procesar el resultado en un callback. Sin este permiso, una aplicación con targetSdk 33+ no puede mostrar notificaciones push. Por debajo de API 33 no se requiere permiso — el código de verificación previene la llamada a APIs no disponibles.

Scoped Storage (Android 10+)

Scoped Storage es uno de los cambios de comportamiento más significativos. A partir de API 29 (targetSdk 29+), la aplicación no puede obtener acceso directo a directorios como Pictures, Downloads, Music y Documents. En su lugar, se usa MediaStore para multimedia, SAF (Storage Access Framework) para archivos arbitrarios y getExternalFilesDir() para su propio almacenamiento. La excepción son las aplicaciones con permiso MANAGE_EXTERNAL_STORAGE, que requiere aprobación de Google Play.

Requisitos de Google Play para API Level y targetSdk

Google Play establece requisitos obligatorios de targetSdkVersion para publicar aplicaciones. Desde agosto de 2024, Google Play exige targetSdkVersion >= API 33 (Android 13). Cada año el umbral aumenta: las nuevas aplicaciones y actualizaciones deben especificar targetSdk no mayor de 1 año desde el API Level principal actual. El incumplimiento del requisito conduce al bloqueo de la publicación y a la eliminación de la aplicación de la tienda.

Por qué Google Play endurece los requisitos

La razón principal es la seguridad. Cada nuevo API Level de Android introduce cambios de comportamiento que cierran vectores de ataque: Scoped Storage (API 29) evita el robo de archivos, POST_NOTIFICATIONS (API 33) protege contra notificaciones spam, Foreground Service Types (API 34) limita los servicios en segundo plano ocultos. Las aplicaciones con targetSdk bajo no reciben estas protecciones y se convierten en una amenaza para los usuarios. Google Play no puede permitir aplicaciones obsoletas en dispositivos modernos.

Verificación del cumplimiento de requisitos

Google Play Console verifica targetSdkVersion al cargar APK/AAB. Si targetSdk está por debajo del requerido — la consola bloquea la publicación con el mensaje: "Your app currently targets API level X and must target at least API level Y". El desarrollador debe actualizar build.gradle, recompilar la aplicación, probar los cambios de comportamiento y volver a cargarla. El formato AAB se recomienda para todas las nuevas publicaciones (obligatorio desde agosto de 2021).

Comprobación del API Level en código: Build.VERSION.SDK_INT

Build.VERSION.SDK_INT es una constante entera estática que contiene el API Level del dispositivo en el que se ejecuta la aplicación. Es la herramienta principal para las comprobaciones de versión de Android en tiempo de ejecución. Build.VERSION_CODES contiene constantes con nombre para cada API Level: VERSION_CODES.TIRAMISU (33), VERSION_CODES.UPSIDE_DOWN_CAKE (34), VERSION_CODES.VANILLA_ICE_CREAM (35). La comparación mediante if (SDK_INT >= VERSION_CODES.TIRAMISU) es el patrón estándar.

// Ejemplos de comprobación de API Level en código Android
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.drawable.AdaptiveIconDrawable

class ApiLevelHelper {

    // 1. Comprobación básica de API Level
    fun isAtLeastTiramisu(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU  // 33
    }

    // 2. Llamada adaptativa a la API con verificación
    fun getAdaptiveIcon(drawable: android.graphics.drawable.Drawable):
            android.graphics.drawable.Drawable? {
        // AdaptiveIconDrawable solo está disponible con API 26 (Android 8)
        if (VERSION.SDK_INT >= VERSION_CODES.O) {
            return AdaptiveIconDrawable(drawable, null)
        }
        return drawable  // fallback para dispositivos antiguos
    }

    // 3. Comprobación del permiso POST_NOTIFICATIONS (solo API 33+)
    fun canRequestNotificationPermission(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU
    }

    // 4. Selección del proveedor de imágenes según API Level
    fun getImagePickerProvider(): String {
        return when {
            VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
                // API 34+ usa PhotoPicker
                "photo_picker"
            }
            VERSION.SDK_INT >= VERSION_CODES.KITKAT -> {
                // API 19+ usa Intent ACTION_OPEN_DOCUMENT
                "open_document"
            }
            else -> {
                // Legacy: ACTION_GET_CONTENT (todas las versiones)
                "get_content"
            }
        }
    }

    // 5. Comprobación estilo Java con @TargetApi (para compatibilidad hacia atrás)
    @Suppress("DEPRECATION")
    fun checkLegacyStorage(): Boolean {
        // El comportamiento de Scoped Storage depende de targetSdk, no de SDK_INT
        return VERSION.SDK_INT < VERSION_CODES.Q  // Android 10
    }

    // 6. Información de compilación para analítica
    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
        )
    }
}

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

La clase ApiLevelHelper demuestra todos los patrones principales de comprobación de API Level: isAtLeastTiramisu con SDK_INT >= VERSION_CODES, getAdaptiveIcon con fallback para versiones antiguas, getImagePickerProvider con when de múltiples ramas, getDeviceApiInfo para analítica. La regla clave es no llamar a nuevas APIs sin verificar SDK_INT, de lo contrario la aplicación fallará con NoSuchMethodError en dispositivos antiguos.

ANT (Android New API) y lint

Android Studio incluye el analizador estático lint, que advierte sobre el uso de APIs por encima de minSdkVersion. Si se llama a un método sin verificar SDK_INT, lint lo marca como error: "Call requires API level 34 (current min is 26)". Soluciones: añadir @RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) al método o una comprobación if de SDK_INT. @TargetApi es una anotación obsoleta, se recomienda @RequiresApi.

Tabla de correspondencia entre API Level y versiones de Android

La tabla de API Level es una herramienta de referencia para el desarrollador. Conociendo el API Level del dispositivo, se puede determinar la versión de Android y las funciones disponibles. La tabla enumera todas las versiones principales de Android desde API Level 1 (2008) hasta API Level 36 (2025). Los nombres en clave (Cupcake, Donut, Tiramisu, VanillaIceCream) se usan internamente en Google y en VERSION_CODES.

Tabla: API Level umbral para cambios de comportamiento

La siguiente tabla muestra los API Level clave que introducen cambios de comportamiento que rompen la compatibilidad hacia atrás al aumentar targetSdk: