Retrofit: qué es, características del cliente HTTP de Android

¿Qué es Retrofit?

Retrofit es una biblioteca para la interacción tipificada con API REST en la plataforma Android, desarrollada por Square. Proporciona una forma declarativa de describir peticiones HTTP a través de interfaces de Java o Kotlin con anotaciones, eliminando por completo la necesidad de analizar JSON manualmente y gestionar conexiones HTTP.

La biblioteca surgió en 2013 como alternativa a soluciones engorrosas como AsyncTask y HttpURLConnection. Para 2025, Retrofit sigue siendo el estándar de facto para la comunicación en red en aplicaciones Android gracias a su simplicidad y seguridad de tipos. Según la encuesta JetBrains Developer Ecosystem 2024, más del 65% de los desarrolladores Android usan Retrofit en proyectos comerciales.

La diferencia clave de Retrofit frente a alternativas es el enfoque declarativo: el desarrollador describe qué hacer (qué endpoint llamar, qué parámetros pasar) en lugar de cómo hacerlo (cómo abrir una conexión, cómo leer un InputStream, cómo analizar JSON). Esto reduce el código boilerplate en un 60–70% en comparación con el uso manual de HttpURLConnection.

Cómo funciona Retrofit

El principio de funcionamiento de Retrofit se basa en proxies dinámicos de Java. Cuando el desarrollador llama a un método de una interfaz anotada, Retrofit intercepta la llamada mediante el mecanismo Proxy.newProxyInstance y la convierte en una petición HTTP. Todo el proceso ocurre en tiempo de ejecución sin generación de código en tiempo de compilación.

Al crear una instancia de Retrofit.Builder se especifican la URL base y la fábrica de convertidores. El Builder configura OkHttpClient — establece tiempos de espera, interceptores, grupo de conexiones y caché. El método create(Class) genera la implementación de la interfaz, devolviendo un objeto proxy que se puede llamar como una clase normal.

La cadena de ejecución de la petición es la siguiente: las anotaciones extraen el método HTTP, los parámetros se sustituyen en la URL o el cuerpo de la petición, el convertidor serializa el cuerpo, OkHttp ejecuta la petición, el convertidor deserializa la respuesta y el resultado se devuelve en el tipo especificado. Cada etapa está aislada y puede ser reemplazada por una implementación personalizada, por ejemplo sustituir OkHttpClient por MockWebServer para pruebas o cambiar el convertidor al modificar la API.

Una característica importante — Retrofit no admite la transmisión de datos en streaming directamente. Para streaming se utiliza OkHttp ResponseBody como tipo de retorno del método de la interfaz. Retrofit tampoco gestiona la cancelación de peticiones automáticamente — para cancelar es necesario guardar una referencia a Call y llamar a cancel(). En Kotlin con funciones suspend, la cancelación de la petición ocurre automáticamente al cancelar la corrutina padre.

Ciclo de vida del objeto Call

Call<T> es un objeto que representa una única petición HTTP. Después de la ejecución (execute o enqueue), un Call no se puede reutilizar — para una nueva petición hay que crear un nuevo Call llamando al método de la interfaz. Esto evita el envío accidental de la misma petición dos veces, que podría provocar operaciones duplicadas en el servidor.

En Kotlin, en lugar de Call se usan funciones suspend, que gestionan automáticamente el ciclo de vida de la petición. Retrofit cambia la ejecución a Dispatchers.IO y devuelve el resultado a la corrutina. Esto reduce el código en un 30–40% en comparación con la versión con Call y Callback.

Anotaciones de Retrofit para métodos HTTP

Las anotaciones son el mecanismo principal de configuración de peticiones HTTP en Retrofit. Cada anotación corresponde a un método HTTP estándar y acepta una ruta relativa al endpoint. Retrofit admite GET, POST, PUT, DELETE, PATCH, HEAD y OPTIONS.

Anotaciones de parámetros de petición

@Path sustituye un valor en un segmento de URL: @Path("id") Int id reemplaza {id} en la ruta. @Query añade un parámetro de consulta: @Query("page") Int page se convierte en ?page=5. @Body pasa un objeto en el cuerpo de la petición con serialización automática mediante el convertidor seleccionado. @Header y @Headers gestionan las cabeceras HTTP — estáticas o dinámicas.

Combinando estas anotaciones se puede describir cualquier endpoint REST. Por ejemplo, para el endpoint POST /api/users/{id}/posts?limit=10 se necesita @POST, @Path para id, @Query para limit y @Body para el objeto pasado. Retrofit ensamblará automáticamente una petición HTTP correcta. También se admiten @Url (URL dinámica), @Field (cuerpo codificado en formulario), @Part y @PartMap para peticiones multipart con archivos.

Ejemplos de código Retrofit en Kotlin

Veamos un ejemplo práctico — una interfaz para la API de GitHub. Se crea una interfaz Kotlin con un método para obtener la lista de repositorios. La clase de datos Repo describe la estructura de la respuesta JSON.

data class Repo(
    val name: String,
    val description: String?,
    val stargazersCount: Int,
    val forksCount: Int
)

interface GitHubApi {
    @GET("users/{user}/repos")
    suspend fun getRepos(
        @Path("user") user: String,
        @Query("sort") sort: String = "updated"
    ): List<Repo>
}

Después de describir la interfaz, se crea una instancia de Retrofit mediante Builder. La URL base, el convertidor y OkHttpClient se configuran una vez y se reutilizan mediante inyección de dependencias.

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.github.com/")
    .addConverterFactory(GsonConverterFactory.create())
    .client(OkHttpClient.Builder()
        .connectTimeout(30, TimeUnit.SECONDS)
        .build())
    .build()

val api = retrofit.create(GitHubApi::class.java)

Manejo de respuestas con envoltorio Response

Para un manejo flexible de los códigos de estado HTTP, use el envoltorio Response<T>. Proporciona acceso al código de respuesta, las cabeceras y el cuerpo sin lanzar excepciones en errores 4xx y 5xx. Esto permite manejar 404 y 500 sin try-catch.

interface GitHubApi {
    @GET("users/{user}/repos")
    suspend fun getRepos(
        @Path("user") user: String
    ): Response<List<Repo>>
}

val response = api.getRepos("octocat")
if (response.isSuccessful) {
    println(response.body()?.size)
} else {
    Log.e("API", "Error: ${response.code()}")
}

Convertidores y serialización en Retrofit

Los convertidores son componentes de Retrofit responsables de convertir objetos a cuerpo HTTP y viceversa. Retrofit no integra la serialización en su núcleo — en su lugar utiliza un enfoque modular mediante Converter.Factory, que permite conectar cualquier biblioteca de serialización.

El convertidor más popular es GsonConverterFactory de Google basado en la biblioteca Gson. Funciona para la mayoría de proyectos, admite TypeAdapter y JsonDeserializer personalizados. Sin embargo, Gson usa reflexión y no respeta la seguridad nula de Kotlin, lo que puede provocar NPE en campos nulos inesperados.

Una alternativa es MoshiConverterFactory de Square: más estricto con los tipos, con mejor soporte de Kotlin (seguridad nula, valores predeterminados) y sin reflexión. Para proyectos en Kotlin puro, lo óptimo es Kotlinx Serialization Converter, que trabaja con anotaciones @Serializable en tiempo de compilación. No usa reflexión, admite sealed class, valores predeterminados y multiplataforma.

La elección del convertidor afecta al rendimiento y la seguridad de tipos. Gson sin configuración personalizada puede deserializar null en un campo no nulo de Kotlin, provocando NPE al acceder. Moshi resuelve este problema mediante la anotación @Json(name) y failOnUnknown. Kotlinx Serialization es el más seguro — genera código en tiempo de compilación, eliminando por completo los errores de tipo en tiempo de ejecución.

Errores comunes al trabajar con Retrofit

La falta de manejo de errores HTTP en funciones suspend es el problema más frecuente. Si el servidor devuelve 4xx o 5xx, Retrofit lanza HttpException. Sin try-catch, la aplicación falla. Usar Response<T> como tipo de retorno soluciona esto, permitiendo comprobar isSuccessful antes de acceder al cuerpo.

La configuración incorrecta del caché provoca tráfico excesivo. Retrofit no almacena en caché las respuestas por sí mismo — esta tarea la realiza OkHttpClient mediante Cache. Sin caché, cada petición se ejecuta completamente, incluso cuando los datos no han cambiado. Añadir un Caché de 10 MB en OkHttpClient reduce el tráfico en un 40–60% en peticiones repetidas de la misma información.

Crear Retrofit para cada petición es un error común de principiantes. Retrofit.Builder es una operación costosa que incluye generación de clases proxy en tiempo de ejecución. La buena práctica es crear una única instancia de Retrofit y reutilizarla mediante frameworks de DI. Hilt, Koin o Dagger proporcionan una instancia singleton de Retrofit para toda la aplicación, ahorrando memoria y acelerando las peticiones.

Ignorar Interceptor para la autorización es el cuarto problema. En lugar de añadir manualmente la cabecera Authorization en cada llamada, configure un Interceptor global en OkHttpClient. El Interceptor intercepta cada petición, añade el token Bearer, y el Authenticator maneja la respuesta 401, renovando el token y repitiendo la petición automáticamente. Esto centraliza la lógica de autenticación.