Saltar a contenido

Tema 3.4 - Retrofit: red, DTOs y errores

La app ya guarda en el móvil. Ahora tiene que hablar con un servidor: pedir datos por HTTPS, convertirlos de JSON a objetos y comportarse bien cuando la red falla.

🟢 Leyenda de repaso obligatorio: los textos con este fondo verde son imprescindibles y entran en todas las evaluaciones del módulo.
Código Descripción
RA 2 Desarrolla aplicaciones para dispositivos móviles analizando y empleando las tecnologías y librerías específicas.
CE e) Se han utilizado las clases necesarias para establecer conexiones y comunicaciones HTTP y HTTPS.
CE j) Se han establecido los permisos requeridos para el funcionamiento de las aplicaciones.

1. Las tres piezas (y quién hace qué)

Pieza Qué hace
DTO Clase que representa exactamente lo que devuelve el servidor
Interfaz del API Declara las llamadas (@GET, @POST…) sin implementarlas
Retrofit Genera la implementación, hace la petición y convierte el JSON

Retrofit no hace magia: por debajo usa OkHttp para la conexión. Tú solo declaras la interfaz y él genera el código que lanza la petición y parsea la respuesta.

2. El DTO: lo que devuelve el servidor

@Serializable                                               // genera el parser a partir de la clase
data class UsuarioRemoto(                                   // lo que devuelve el servidor
    val id: Int,                                            // campo id del JSON
    val login: String,                                      // campo login del JSON
    val html_url: String                                    // campo html_url del JSON
)

El DTO copia el JSON del servidor, no tu modelo de negocio. Si el servidor llama login, tu DTO tiene login; la conversión a tu modelo se hace después.

3. La interfaz: declarar la llamada

interface AgendaApi {                                       // contrato del servidor
    @GET("users")                                           // GET https://api.github.com/users
    suspend fun usuarios(): List<UsuarioRemoto>              // suspend: la llamada no bloquea la UI
}

suspend es obligatorio: la petición se hace en segundo plano y la función se reanuda cuando llega la respuesta, sin bloquear la interfaz.

4. El cliente: Retrofit + JSON

object RetrofitCliente {                                    // una sola instancia del cliente
    private val json = Json { ignoreUnknownKeys = true }     // si el servidor añade campos, no revienta
    private val retrofit = Retrofit.Builder()
        .baseUrl("https://api.github.com/")                 // URL base (termina en /)
        .addConverterFactory(json.asConverterFactory("application/json".toMediaType()))
        .build()
    val api: AgendaApi = retrofit.create(AgendaApi::class.java) // implementación generada
}

Json { ignoreUnknownKeys = true } es la diferencia entre aguantar un cambio del servidor y crashear en producción.

Permisos: sin esto no hay red (CE j)

<uses-permission android:name="android.permission.INTERNET" />

Sin esa línea, toda petición falla con EPERM en getaddrinfo: parece un error de red y es de permisos.

5. La pantalla: tres estados, no uno

Una pantalla que llama a un servidor tiene tres estados: cargando, error y datos.

fun EscenaApi() {                                           // 3.4: pedir datos a un servidor
    val alcance = rememberCoroutineScope()
    var usuarios by remember { mutableStateOf<List<UsuarioRemoto>>(emptyList()) }
    var error by remember { mutableStateOf<String?>(null) }
    var cargando by remember { mutableStateOf(false) }
    Scaffold(topBar = { TopAppBar(title = { Text("IsmaelAgenda · API") }) }) { relleno ->
        Column(
            Modifier.fillMaxSize().padding(relleno).padding(16.dp),
            verticalArrangement = Arrangement.spacedBy(12.dp)
        ) {
            Row(horizontalArrangement = Arrangement.spacedBy(12.dp)) {
                Button(onClick = {
                    alcance.launch {
                        cargando = true; error = null             // estado de carga
                        try {
                            usuarios = RetrofitCliente.api.usuarios() // llamada real por HTTPS
                        } catch (e: Exception) {                  // sin red, timeout, 404...
                            error = e.message ?: "Error desconocido"
                        } finally {
                            cargando = false                      // pase lo que pase, quita la rueda
                        }
                    }
                }) { Text("Cargar usuarios") }
                Button(onClick = {
                    alcance.launch {
                        cargando = true; error = null
                        try {
                            usuarios = Retrofit.Builder()        // cliente MAL configurado a propósito
                                .baseUrl("https://api.github.com/noexiste/")
                                .addConverterFactory(json2().asConverterFactory("application/json".toMediaType()))
                                .build()
                                .create(AgendaApi::class.java)
                                .usuarios()
                        } catch (e: Exception) {
                            error = e.message ?: "Error desconocido" // 404 del servidor
                        } finally {
                            cargando = false
                        }
                    }
                }) { Text("Provocar error") }
            }
            if (cargando) CircularProgressIndicator()          // rueda mientras espera
            error?.let { Text("ERROR: $it", color = MaterialTheme.colorScheme.error) }
            Text("Usuarios recibidos: ${usuarios.size}", style = MaterialTheme.typography.titleMedium)
            LazyColumn(Modifier.weight(1f), verticalArrangement = Arrangement.spacedBy(8.dp)) {
                items(usuarios) { u ->
                    Card(Modifier.fillMaxWidth()) {
                        Column(Modifier.padding(12.dp)) {
                            Text("${u.id} · ${u.login}", style = MaterialTheme.typography.titleMedium)
                            Text(u.html_url, style = MaterialTheme.typography.bodyMedium)
                        }
                    }
                }
            }
        }
    }
}

Pantalla API antes de pedir nada, con el contador a cero y sin error

Figura 1. Estado inicial: sin petición, «Usuarios recibidos: 0», sin error.

Pantalla API con 30 usuarios cargados por HTTPS desde la API de GitHub

Figura 2. Petición correcta por HTTPS (CE e): 30 usuarios.

Pantalla API con el mensaje ERROR: HTTP 404 y la lista anterior conservada

Figura 3. Error controlado: el servidor responde 404, la app lo muestra en rojo y conserva los datos que tenía.

Un error de red no es una excepción que se ignora: es un estado más de la pantalla. Se muestra, se explica y se permite reintentar.

6. Fallos habituales

Síntoma Causa Solución
EPERM en getaddrinfo falta el permiso INTERNET añadirlo al Manifest y recompilar
CertPathValidatorException: Trust anchor not found el certificado del dominio no encadena con una CA del móvil usar un dominio con cadena válida o instalar la CA (solo en desarrollo)
HTTP 404 la ruta no existe revisar baseUrl + @GET
HTTP 401/403 falta token o permisos cabecera Authorization
SocketTimeoutException el servidor no responde timeouts y reintento
La app se cierra al pedir excepción no capturada try/catch/finally alrededor de la llamada

finally { cargando = false } no es opcional: si la petición falla y no lo pones, la rueda de carga se queda girando para siempre y el usuario cree que la app está colgada.

Lo que tienes que llevarte de este apartado

  • baseUrl termina en / y la ruta del @GET no empieza por /: si no respetas esa convención, la URL sale mal y el error es un 404 despistado.
  • El tiempo de espera también es configurable: sin callTimeout, un servidor colgado deja la pantalla con la rueda girando para siempre.
  • Un 401 y un 404 se tratan distinto: el primero pide renovar la sesión, el segundo avisar y salir de la pantalla.

Presentación