Retrofit: la API como interfaz

La primera idea que hay que desalojar es que Retrofit sea un cliente HTTP. No lo es, y creerlo explica la mitad de las confusiones posteriores. Retrofit no abre sockets, no negocia TLS, no mantiene conexiones vivas ni decide tiempos de espera: todo eso lo hace OkHttp, que vive por debajo y que veremos en la lección siguiente. Lo que Retrofit aporta es una cosa mucho más específica y mucho más interesante desde el punto de vista del diseño: un mecanismo para expresar el contrato de una API remota como un tipo del lenguaje. Declaras una interfaz, la anotas, y en tiempo de ejecución recibes una implementación que traduce cada llamada a función en una petición y cada respuesta en un valor tipado. El desplazamiento conceptual es notable. Deja de haber código que construye peticiones y empieza a haber una declaración de qué existe al otro lado, con el mismo estatus que cualquier otra interfaz del proyecto. Y como toda declaración, se puede leer, se puede sustituir por un doble en las pruebas y se puede razonar sin ejecutarla.

La interfaz no es documentación: es el programa

Cuando pides una implementación de tu interfaz, Retrofit no genera código fuente ni ejecuta ningún procesador de anotaciones. Construye un objeto delegado dinámico que intercepta cada invocación, y la primera vez que se llama a una función concreta analiza sus anotaciones y su firma para fabricar un plan de ejecución que después queda memorizado. Ese detalle tiene dos consecuencias prácticas. La primera es que los errores de declaración no aparecen al compilar sino al invocar por primera vez esa función concreta, con un mensaje que nombra la función culpable. La segunda es que el coste del análisis se paga una sola vez por método y no en cada petición.

El contrato se expresa con tres familias de anotaciones que conviene no mezclar mentalmente: las que fijan el verbo y la ruta, las que inyectan valores en la petición y las que describen el cuerpo.

interface ApiCatalogo {
    @GET("v1/productos/{id}")
    suspend fun producto(
        @Path("id") id: String,
        @Query("expandir") expandir: List<String> = emptyList(),
    ): Producto

    @POST("v1/pedidos")
    suspend fun crearPedido(
        @Header("Idempotency-Key") clave: String,
        @Body pedido: PedidoNuevo,
    ): Response<PedidoCreado>
}

La resolución de la ruta relativa contra la dirección base sigue las reglas de resolución de URL, no una concatenación de cadenas, y ahí se esconde una de las trampas más repetidas del ecosistema. Una dirección base que no termina en barra descarta su último segmento al resolver, y una ruta relativa que empieza por barra descarta la ruta entera de la base. El resultado es una petición dirigida a un sitio que nadie escribió y que suele responder con un 404 desconcertante. La regla operativa cabe en una línea: la base termina en barra, las rutas relativas nunca empiezan por ella.

La instancia que fabrica las implementaciones se compone de tres piezas y ninguna es accesoria: la dirección base, el cliente de transporte que ejecutará las llamadas y al menos una fábrica de convertidores que sepa traducir entre cuerpos y tipos. Que el cliente se inyecte desde fuera en lugar de dejar que se cree uno por omisión es lo que permite compartir conexiones, interceptores y caché con el resto de la aplicación, tal como veremos en la lección siguiente.

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.ejemplo.com/v1/")   // siempre termina en barra
    .client(clienteOkHttpCompartido)
    .addConverterFactory(analizador.asConverterFactory(tipoJson))
    .build()

val api: ApiCatalogo = retrofit.create()

El orden en que se registran las fábricas importa, porque se consultan en secuencia y gana la primera que declare saber manejar el tipo pedido. Registrar una fábrica especializada en un tipo concreto después de una genérica equivale a no registrarla, y ese es el mecanismo por el que un tipo envoltorio propio deja de recibir el tratamiento que se le había preparado.

Qué significa exactamente marcar la función como suspend

Una función suspend en el contrato no se convierte en nada mágico. Retrofit detecta que el último parámetro real de la firma compilada es una continuación, envuelve la llamada asíncrona de OkHttp y reanuda esa continuación cuando llega la respuesta o cuando falla el transporte. La cancelación viaja en sentido contrario: si la corrutina que espera se cancela, se invoca la cancelación de la llamada subyacente, que cierra el socket si la petición estaba en vuelo.

De ahí se sigue una propiedad que se enuncia mucho y se entiende poco: estas funciones son seguras desde el hilo principal. No porque Retrofit cambie de hilo por ti, sino porque nunca hubo bloqueo que trasladar. La petición se encola en el repartidor de OkHttp, que tiene sus propios hilos, y la corrutina que la espera queda suspendida sin ocupar ninguno. Envolver la llamada en un cambio explícito al despachador de entrada y salida no la hace más correcta ni más rápida: añade un salto de contexto que no resuelve ningún problema.

Conviene además recordar que el mecanismo anterior a las corrutinas sigue existiendo y ocasionalmente sigue siendo el adecuado. Una función que devuelve Call entrega un objeto ejecutable que se puede encolar, cancelar o repetir manualmente, y una fábrica de adaptadores permite que el tipo de retorno sea un flujo o cualquier otra abstracción. Las funciones suspend no son un adaptador más: están integradas en el núcleo. Pero saber que el punto de extensión existe evita reescribir a mano lo que ya está previsto.

Tres desenlaces, no dos

Aquí está el error conceptual más caro de esta lección, y merece enunciarse sin rodeos. Una llamada HTTP no tiene dos finales posibles sino tres, y confundir dos de ellos produce código que trata como catástrofe lo que era una respuesta perfectamente válida del servidor.

El primero es que la petición llegue, el servidor conteste con un código de éxito y el convertidor sepa transformar el cuerpo. El segundo es que la petición llegue, el servidor conteste con un código de error y devuelva un cuerpo que explica qué pasó. El tercero es que la petición no llegue a completarse en absoluto: no hay red, el nombre no resuelve, expira el tiempo de espera, el certificado no valida o el socket se corta. Los dos primeros son conversaciones que terminaron; el tercero es una conversación que nunca ocurrió.

flowchart TD
A[Llamada suspend en el repositorio] --> B{Se completo el intercambio}
B -->|No| C[Fallo de transporte tipo IOException]
B -->|Si| D{Codigo de estado en el rango de exito}
D -->|Si| E[Convertidor produce el cuerpo tipado]
D -->|No| F[Respuesta de error con cuerpo propio]
E --> G[Valor de dominio]
F --> H[Traduccion a error de dominio]
C --> H
style E fill:#a6e3a1,color:#11111b
style F fill:#f9e2af,color:#11111b
style C fill:#f38ba8,color:#11111b

El tipo de retorno que declares decide cómo se te presentan esos tres desenlaces. Si declaras el tipo del cuerpo directamente, Retrofit te entrega el valor cuando todo fue bien y lanza una excepción en los otros dos casos: una excepción de HTTP cuando el servidor respondió con error y una excepción de entrada y salida cuando falló el transporte. Si declaras Response envolviendo el tipo, la respuesta de error deja de ser excepcional y llega como un objeto que puedes interrogar, mientras que el fallo de transporte sigue siendo una excepción porque no hay nada que interrogar.

suspend fun cargarProducto(id: String): ResultadoDominio<Producto> = try {
    val respuesta = api.producto(id)
    ResultadoDominio.Exito(respuesta)
} catch (e: HttpException) {
    ResultadoDominio.Fallo(traducirCodigo(e.code(), e.response()?.errorBody()))
} catch (e: IOException) {
    ResultadoDominio.Fallo(ErrorDominio.SinConexion)
}

El cuerpo de error merece una advertencia técnica concreta porque su mal uso produce fugas silenciosas. Es un flujo que se puede leer una sola vez y que debe cerrarse; leerlo dos veces devuelve vacío y no leerlo nunca deja una conexión retenida hasta que el recolector la libere. Además, para deserializarlo con el mismo convertidor que usa el resto de la API hay que pedírselo explícitamente a la instancia de Retrofit, porque la conversión automática solo se aplica a los cuerpos de éxito.

val convertidor = retrofit.responseBodyConverter<ErrorApi>(
    ErrorApi::class.java, emptyArray()
)

fun leerError(cuerpo: ResponseBody?): ErrorApi? =
    cuerpo?.use { runCatching { convertidor.convert(it) }.getOrNull() }

Dónde termina el contrato y empieza el dominio

Una interfaz de Retrofit describe fielmente lo que existe al otro lado del cable, con sus nombres de campo ajenos, sus códigos numéricos y sus convenciones. Esa fidelidad es una virtud dentro de la capa de red y un defecto en cuanto se propaga hacia arriba. Una excepción de HTTP viajando hasta un modelo de vista significa que la interfaz de usuario conoce el vocabulario del servidor, y a partir de ahí cualquier cambio remoto atraviesa la aplicación entera.

La frontera correcta es el repositorio, y su trabajo consiste en traducir tres alfabetos en uno: códigos de estado, cuerpos de error y fallos de transporte se convierten en un tipo cerrado propio que enumera lo que tu aplicación sabe hacer. Un 401 no es un número, es sesión caducada. Un 422 con un cuerpo que enumera campos no es un error genérico, es validación fallida con detalle. Un 503 no es un fallo del cliente, es indisponibilidad temporal que quizá merezca reintento.

private fun traducirCodigo(codigo: Int, cuerpo: ResponseBody?): ErrorDominio =
    when (codigo) {
        401 -> ErrorDominio.SesionCaducida
        403 -> ErrorDominio.SinPermiso
        404 -> ErrorDominio.NoEncontrado
        422 -> ErrorDominio.Validacion(leerError(cuerpo)?.campos.orEmpty())
        in 500..599 -> ErrorDominio.Servidor(codigo)
        else -> ErrorDominio.Inesperado(codigo)
    }

Esa función es más importante de lo que su tamaño sugiere, porque es el único punto del sistema donde el vocabulario ajeno se convierte en propio. Todo lo que quede por encima de ella puede escribirse, leerse y probarse sin saber que existe HTTP, y esa independencia es exactamente lo que permite sustituir la fuente remota por una local, o cambiar de biblioteca, sin tocar una sola pantalla.