Retrofit — qué es, biblioteca HTTP y uso en aplicaciones

¿Qué es Retrofit?

Retrofit es una biblioteca para realizar solicitudes HTTP en aplicaciones Android, desarrollada por Square. Proporciona un enfoque declarativo para definir APIs REST a través de interfaces Java con anotaciones, haciendo que el código de interacción en red sea limpio y predecible.

La idea principal de Retrofit es que el desarrollador describe la API como una interfaz con métodos y anotaciones, y la biblioteca genera la implementación automáticamente. Este enfoque garantiza que todos los endpoints estén tipificados y que los errores en URL o parámetros se detecten en tiempo de compilación, no en tiempo de ejecución.

Retrofit admite todos los métodos HTTP populares y formatos de datos. La biblioteca es activamente mantenida por Square y la comunidad: las nuevas versiones se publican regularmente, y la versión actual 2.11 incluye soporte para Java 17 y Kotlin 2.0. Retrofit sigue siendo el cliente HTTP más popular para Android.

Retrofit funciona sobre OkHttp, un cliente HTTP eficiente también de Square. Esta combinación proporciona almacenamiento en caché, interceptación de solicitudes y gestión de conexiones a nivel de protocolo de transporte. La biblioteca admite llamadas tanto síncronas como asíncronas.

Desde su primer lanzamiento en 2013, Retrofit ha pasado por varias actualizaciones importantes. La versión actual Retrofit 2 ha sido completamente reescrita basándose en la experiencia de la primera versión y ofrece un sistema más flexible de convertidores y adaptadores para la asincronía.

La arquitectura de Retrofit sigue el principio de separación de responsabilidades: la interfaz define solo el contrato de la API, los convertidores manejan la serialización y los adaptadores gestionan la asincronía. Esto permite reemplazar cualquier componente sin cambiar el resto del código. Por ejemplo, puedes cambiar de Gson a Moshi sin modificar las definiciones de los endpoints.

Características principales de Retrofit

Retrofit proporciona un conjunto de funciones que cubren prácticamente todos los escenarios de interacción en red en aplicaciones móviles. La ventaja clave es el estilo declarativo de definición de API.

Anotaciones declarativas de endpoints

Las anotaciones @GET, @POST, @PUT, @PATCH, @DELETE y @HTTP permiten especificar el método HTTP y la plantilla de URL directamente en la interfaz. Los parámetros de ruta se establecen mediante @Path, los parámetros de consulta mediante @Query y el cuerpo de la solicitud mediante @Body. Este enfoque hace que la capa de API de la aplicación esté completamente tipificada.

Convertidores para serialización

Los convertidores transforman las respuestas HTTP en objetos Java y viceversa. Retrofit admite Gson, Moshi, Jackson, Protobuf y Wire. El desarrollador conecta el convertidor necesario a través de Converter.Factory, y la biblioteca lo aplica automáticamente a todas las solicitudes y respuestas.

Adaptadores para asincronía

Los adaptadores CallAdapter permiten cambiar el tipo de retorno de los métodos de la API. En lugar del Call estándar, se puede usar Observable para RxJava, Deferred para corrutinas Kotlin o LiveData. Esto integra las solicitudes de red con la arquitectura de aplicación elegida.

URLs dinámicos y encabezados

Las URLs dinámicas se establecen mediante la anotación @Url, lo que permite pasar el endpoint en tiempo de ejecución. Los encabezados se pueden especificar estáticamente mediante @Headers o dinámicamente mediante el parámetro @Header. Para encabezados globales en todas las solicitudes, se utiliza un interceptor de OkHttp que agrega encabezados a cada solicitud saliente.

¿Cómo funciona Retrofit?

Retrofit funciona en tres etapas: definir la interfaz de la API, crear una instancia de Retrofit y ejecutar la solicitud. La biblioteca genera la implementación de la interfaz en tiempo de ejecución basándose en las anotaciones y los convertidores.

Ciclo de vida de la solicitud

Cuando se llama a un método de la API, Retrofit crea un objeto Request basado en las anotaciones y los argumentos. La solicitud se pasa a OkHttp para su ejecución. Después de recibir la respuesta, la biblioteca la pasa a Converter.Factory para transformarla al tipo requerido. CallAdapter envuelve el resultado en un envoltorio asíncrono. Cada etapa se puede personalizar.

interface ApiService {
    @GET("users/{id}")
    suspend fun getUser(@Path("id") id: Int): User
}

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .addConverterFactory(GsonConverterFactory.create())
    .build()

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

Instalación y configuración de Retrofit

La instalación de Retrofit se realiza a través de Gradle, el sistema de compilación estándar de Android. La biblioteca se distribuye a través de Maven Central y requiere agregar varias dependencias al build.gradle del proyecto.

Agregar dependencias

En el archivo build.gradle (a nivel de módulo), agregue dependencias para Retrofit, el convertidor Gson y OkHttp. Se recomienda extraer las versiones de las bibliotecas en variables en el build.gradle raíz para una gestión centralizada. Retrofit 2 requiere un mínimo de Android API 21.

dependencies {
    implementation "com.squareup.retrofit2:retrofit:2.11.0"
    implementation "com.squareup.retrofit2:converter-gson:2.11.0"
    implementation "com.squareup.okhttp3:okhttp:4.12.0"
    implementation "com.squareup.okhttp3:logging-interceptor:4.12.0"
}

Crear una instancia de Retrofit

Una instancia de Retrofit se crea mediante Builder. Parámetros obligatorios: baseUrl y ConverterFactory. Se recomienda usar un singleton para Retrofit y OkHttpClient para evitar crear conexiones redundantes. Agregar un logging-interceptor simplifica la depuración de solicitudes de red durante el desarrollo.

Para proyectos Kotlin, se recomienda usar funciones suspend en la interfaz de la API en lugar de tipos Call. Esto simplifica el código y permite usar la concurrencia estructurada de las corrutinas. Al cambiar de Call a suspend, solo necesita cambiar el tipo de retorno en la interfaz; el resto del código se adapta automáticamente.

Ejemplos de uso de Retrofit

Los ejemplos a continuación muestran escenarios típicos de trabajo con Retrofit en aplicaciones Android: desde una simple solicitud GET hasta la carga de un archivo al servidor.

Solicitud GET con parámetros de consulta

Una solicitud GET simple con parámetros de cadena de consulta es una operación básica. La anotación @Query agrega parámetros a la URL automáticamente, y la función suspend permite llamar a la solicitud desde una corrutina sin bloquear el hilo principal.

interface UserApi {
    @GET("users")
    suspend fun getUsers(
        @Query("page") page: Int,
        @Query("limit") limit: Int = 20
    ): List<User>
}

val users = api.getUsers(page = 1)

Solicitud POST con cuerpo JSON

Una solicitud POST con cuerpo JSON usa la anotación @Body para pasar el objeto. GsonConverterFactory serializa automáticamente el objeto User en JSON. Las corrutinas Kotlin garantizan que la solicitud se ejecute en el hilo de fondo sin interfaces Callback.

interface UserApi {
    @POST("users")
    suspend fun createUser(@Body user: User): User
}

val user = User(name = "Ana Ivanova", email = "anna@example.com")
val created = api.createUser(user)

Carga de archivo mediante Multipart

La anotación @Multipart con @Part permite cargar archivos al servidor. Retrofit forma automáticamente una solicitud multipart con los encabezados necesarios. OkHttp gestiona el progreso de la carga a través de RequestBody, lo que permite mostrar un indicador al usuario.

interface FileApi {
    @Multipart
    @POST("upload")
    suspend fun uploadImage(
        @Part file: MultipartBody.Part
    ): UploadResponse
}

val body = "image.jpg".toRequestBody("image/jpeg".toMediaTypeOrNull())
val part = MultipartBody.Part.createFormData("file", "image.jpg", body)

Manejo de errores e interceptores en Retrofit

El manejo de errores en Retrofit se basa en una combinación de mecanismos de OkHttp y corrutinas Kotlin. Los interceptores de OkHttp permiten registrar solicitudes, agregar encabezados de autenticación y manejar errores antes de que lleguen al código de la aplicación.

Para el manejo centralizado de errores, a menudo se crea un envoltorio alrededor de las llamadas a la API como una clase sellada Result. Dicha clase tiene dos subclases: Success con datos y Error con una excepción. El ViewModel recibe un resultado unificado y puede mostrar el estado correspondiente de la interfaz de usuario sin duplicar el código de manejo de errores en cada función.

Los interceptores son de dos tipos: los interceptores de aplicación modifican la solicitud antes de enviarla al servidor, y los interceptores de red trabajan con la respuesta después de recibirla. Por ejemplo, un interceptor puede renovar automáticamente el token de acceso al recibir un 401 y repetir la solicitud con el nuevo token sin intervención del desarrollador.

Registro de solicitudes mediante Interceptor

El interceptor de registro HttpLoggingInterceptor es una herramienta indispensable para depurar solicitudes de red. Muestra en Logcat el método de solicitud, la URL, los encabezados, el cuerpo y el código de respuesta. El nivel de registro se puede configurar: BASIC para información mínima, HEADERS para encabezados o BODY para contenido completo. En producción, se recomienda usar BASIC o deshabilitar el registro por completo.

Los interceptores en OkHttp se dividen en dos tipos: interceptores de aplicación para modificar la solicitud e interceptores de red para trabajar con datos de red sin procesar. El interceptor de registro muestra automáticamente los detalles de la solicitud y la respuesta en Logcat.

El manejo de errores a nivel de corrutinas se realiza mediante try-catch alrededor de la llamada a la función suspend. Retrofit devuelve errores como HttpException para códigos 4xx y 5xx, UnknownHostException cuando no hay red y SocketTimeoutException cuando se supera el tiempo de espera. Se recomienda usar una clase sellada Result para el manejo unificado.