Alamofire — qué es, cliente HTTP en Swift y cómo funciona

¿Qué es Alamofire?

Alamofire es un cliente HTTP para Swift creado por Alamofire Software Foundation (originalmente por Mattt Thompson en 2014). La biblioteca abstrae los detalles de bajo nivel de URLSession, proporcionando una API limpia y expresiva para la comunicación en red.

La filosofía principal de Alamofire es la sintaxis de encadenamiento, donde los parámetros de la petición (URL, método, cabeceras, parámetros, codificador) se pasan mediante llamadas secuenciales. Esto hace que el código sea más legible y reduce la probabilidad de errores relacionados con una configuración incorrecta de URLRequest. El enfoque declarativo permite centrarse en lo que hay que hacer, no en los detalles de cómo configurar la conexión. El desarrollador describe el resultado deseado y la biblioteca se encarga del trabajo de red de bajo nivel.

La biblioteca se ha mantenido activamente desde 2014 y ha pasado por siete versiones principales. Alamofire 5, actual a partir de 2025–2026, incluye soporte para Combine, async/await, convertidores de respuesta, EventMonitor para depuración y RequestInterceptor para interceptar peticiones. Cada versión principal trajo mejoras significativas: Alamofire 4 añadió soporte para Codable, Alamofire 5 añadió Combine Publishers y un sistema mejorado de intercepción de peticiones.

El ecosistema de Alamofire incluye bibliotecas adicionales: AlamofireImage para carga y caché de imágenes, AlamofireNetworkActivityIndicator para el indicador de red en la barra de estado de iOS y AlamofireObjectMapper para integración con ObjectMapper. Estos componentes hacen de Alamofire un stack de red completo, no solo un cliente HTTP.

Instalación y configuración

Alamofire se instala mediante Swift Package Manager (recomendado), CocoaPods o Carthage. En Xcode, simplemente abre el menú File → Add Packages, pega la URL del repositorio y especifica la versión.

// Swift Package Manager — añadir a Package.swift
dependencies: [
    .package(url: "https://github.com/Alamofire/Alamofire.git",
             from: "5.9.0")
]

// Importar en el archivo
import Alamofire

Después de la instalación, Alamofire está disponible globalmente a través del espacio de nombres AF(abreviatura de Alamofire) sin configuración adicional. La mayoría de los proyectos comienzan configurando una Session con su propia configuración — esto permite establecer una URL base, cabeceras predeterminadas, tiempos de espera y manejadores de certificados TLS.

let configuration = URLSessionConfiguration.default
configuration.timeoutIntervalForRequest = 30
let session = Session(configuration: configuration)

Crear una sesión personalizada mediante Session(configuration:) es necesario cuando se requiere una configuración única para diferentes partes de la aplicación — por ejemplo, una sesión separada para descargas de imágenes con caché agresiva y otra separada para peticiones API con autenticación. La Session de Alamofire acepta no solo configuración, sino también un interceptor, serverTrustManager, cachedResponseHandler y redirectHandler, proporcionando control total sobre el comportamiento de red en todas las etapas de la petición.

Características principales

Alamofire proporciona una amplia gama de funciones que cubren la mayoría de los escenarios de interacción de red en aplicaciones iOS. Veamos las principales.

Peticiones HTTP

La sintaxis básica de una petición incluye el método, URL, parámetros y codificación. Todos los métodos HTTP estándar son compatibles mediante el enum HTTPMethod: get, post, put, patch, delete. Los parámetros pueden codificarse como parámetros URL (URLEncoding), cuerpo JSON (JSONEncoding) o datos multiparte (MultipartFormData).

AF.request("https://api.example.com/users", method: .post,
           parameters: ["name": "Alex", "role": "developer"])
    .validate()
    .responseDecodable(of: User.self) { response in
        switch response.result {
        case .success(let user):
            print("Creado por el usuario: \(user)")
        case .failure(let error):
            print("Error: \(error)")
        }
    }

El método validate() comprueba automáticamente el código de estado (200–299) y el tipo de contenido, devolviendo un error en caso de respuesta inesperada, eliminando la comprobación manual de statusCode. responseDecodable utiliza el protocolo Decodable para la deserialización automática de JSON en estructuras Swift — esto elimina la JSONSerialization manual y reduce el código repetitivo al trabajar con APIs REST.

Manejo de respuestas

Alamofire admite varios tipos de manejadores de respuesta: response (datos brutos), responseJSON (diccionario/array), responseString (texto), responseData (Data) y responseDecodable (modelo Decodable). Los convertidores de respuesta pueden ser personalizados — para protobuf, formatos gráficos o protocolos propios.

Carga y descarga de archivos

Para subir datos al servidor se utiliza upload, que admite Data, File y MultipartFormData. La descarga de archivos grandes se realiza mediante download con la posibilidad de reanudar a través de resumeData tras una interrupción de la conexión. Ambas operaciones admiten seguimiento del progreso mediante uploadProgress y downloadProgress con valores fraccionarios de 0 a 1 para mostrar en la interfaz de usuario.

La carga multiparte con Alamofire es especialmente cómoda: el método upload(multipartFormData:) acepta un cierre donde se añaden las partes del formulario mediante append. Cada parte puede contener datos, un archivo o un flujo, así como su propio nombre y tipo mime. Alamofire calcula automáticamente los límites multiparte y establece la cabecera Content-Type correcta, ahorrando al desarrollador la formación manual del cuerpo de la petición. Para archivos grandes, se recomienda usar proveedores de flujo en lugar de cargar todo el archivo en memoria — esto evita superar el límite de memoria en dispositivos móviles con recursos limitados. Un escenario típico es enviar un avatar de usuario junto con los datos del perfil en una única petición multiparte, lo que reduce el número de llamadas HTTP y simplifica el procesamiento en el servidor.

Alamofire vs URLSession

Comparar Alamofire con URLSession nativo ayuda a tomar decisiones arquitectónicas. Alamofire no reemplaza a URLSession — se construye sobre él y utiliza los mismos mecanismos de configuración, caché y tareas en segundo plano. Todas las funciones de URLSession son accesibles a través de Alamofire, pero con una sintaxis declarativa más cómoda.

En proyectos grandes, Alamofire reduce el código de peticiones de red en un 30–50% y simplifica el manejo de errores. En proyectos pequeños o cuando el tamaño del binario es una restricción estricta, URLSession nativo es preferible debido a la ausencia de dependencias externas.

Alamofire 5 moderno se integra con Combine mediante la propiedad publishDecodable, que devuelve un Publisher, permitiendo cadenas de peticiones reactivas con manejo de errores y transformación de datos. Para async/await, están disponibles los métodos con el sufijo value — por ejemplo, AF.request(url).serializingDecodable(User.self).value, haciendo que la sintaxis sea extremadamente concisa y similar al trabajo con URLSession nativo. Al usar async/await, los cierres ya no son necesarios y el manejo de errores se realiza mediante bloques do-catch estándar de Swift, simplificando el mantenimiento del código y su legibilidad a largo plazo.

Ejemplos de código

Veamos un ejemplo más complejo — una petición con un interceptor que añade automáticamente un token de autorización y realiza un reintento en caso de error 401. Este es un escenario típico para aplicaciones con autenticación JWT.

class AuthInterceptor: RequestInterceptor {
    func adapt(_ urlRequest: URLRequest,
               for session: Session,
               completion: @escaping (Result<URLRequest, Error>) -> Void) {
        var request = urlRequest
        request.setValue("Bearer \(TokenManager.shared.token)",
                         forHTTPHeaderField: "Authorization")
        completion(.success(request))
    }

    func retry(_ request: Request,
              for session: Session,
              dueTo error: Error,
              completion: @escaping (RetryResult) -> Void) {
        guard let response = request.response,
              response.statusCode == 401
        else { return completion(.doNotRetry) }
        TokenManager.shared.refreshToken { success in
            completion(success ? .retry : .doNotRetry)
        }
    }
}

El AuthInterceptor implementa dos protocolos: adapt (añade un token a cada petición) y retry (intenta renovar el token ante un error 401). El método retry comprueba el código de estado de la respuesta y, si se recibe un 401, solicita un nuevo token mediante TokenManager. Tras una renovación exitosa, la petición se reintenta automáticamente.

Uso del interceptor con una sesión:

let session = Session(interceptor: AuthInterceptor())
session.request("https://api.example.com/profile")
    .responseDecodable(of: Profile.self) { response in
        print(response.result)
    }

Todas las peticiones a través de esta sesión pasan automáticamente por AuthInterceptor — el token se añade a las cabeceras y, ante un 401, se realiza una renovación y reintento. Esto elimina la duplicación de código de autenticación en cada petición y centraliza la lógica de gestión de tokens.