URLSession — o que é, API de rede e como funciona no iOS

O que é URLSession?

URLSession é uma API para operações de rede apresentada pela Apple no iOS 7 e macOS 10.9. Ela substituiu o NSURLConnection e forneceu um modelo mais flexível e poderoso para trabalhar com a rede. A biblioteca suporta HTTP/1.1, HTTP/2, HTTP/3 e WebSocket, além de sessões em segundo plano para carregamento de dados.

A principal vantagem da URLSession sobre o antigo NSURLConnection é o suporte para múltiplas conexões simultâneas através de uma única sessão, configurações personalizáveis e a capacidade de pausar e retomar downloads. Uma sessão combina um grupo de tarefas de rede com configurações compartilhadas: cache, política de cookies, timeouts, certificados TLS.

No iOS, a URLSession trabalha com o cache DNS do sistema, gerenciamento de energia e processos em segundo plano. Quando o aplicativo é minimizado, o sistema pode continuar carregando dados através de uma sessão em segundo plano e, ao concluir, notificar o aplicativo através de um manipulador de conclusão. As sessões em segundo plano são especialmente úteis para baixar arquivos grandes, atualizar conteúdo e sincronizar dados em aplicativos de documentos e mídia. Para trabalhar com sessões em segundo plano, você precisa implementar o URLSessionDelegate e passar um identificador de configuração ao criar a sessão — o sistema usa este identificador para restaurar a sessão após uma reinicialização do aplicativo.

Uma vantagem importante da URLSession é o suporte para HTTP/2 e HTTP/3. A multiplexação HTTP/2 permite enviar múltiplas requisições através de uma única conexão TCP, reduzindo a latência e a carga do servidor. O HTTP/3, baseado no protocolo QUIC sobre UDP, proporciona um estabelecimento de conexão ainda mais rápido ao eliminar o handshake TCP.

Arquitetura da URLSession

A arquitetura da URLSession consiste em três componentes principais: configuração da sessão, a sessão em si e as tarefas. Cada componente é responsável por um aspecto da interação de rede, e sua combinação determina o comportamento do aplicativo ao trabalhar com a rede.

URLSessionConfiguration

A configuração define os parâmetros da sessão — desde timeouts até políticas de cache. Existem três tipos: .default (padrão com cache em disco), .ephemeral (sem salvar cache e cookies) e .background (para downloads em segundo plano). Na configuração, você pode especificar o número máximo de conexões por host, timeout de requisição e recurso, política TLS e configurações de proxy.

Tipos de URLSessionTask

URLSessionTask é a classe base para todas as operações de rede. As principais subclasses são: URLSessionDataTask para requisições GET e POST que retornam dados na memória, URLSessionDownloadTask para baixar arquivos para o disco, URLSessionUploadTask para enviar arquivos ao servidor e URLSessionWebSocketTask para trabalhar com WebSocket desde o iOS 13.

Delegates da URLSession

O delegate da sessão recebe eventos sobre o progresso das tarefas: recebimento de dados, conclusão de download, erros de autenticação, redirecionamentos. O URLSessionDelegate e seus subprotocolos permitem interceptar certificados TLS durante a autenticação, gerenciar o cache de respostas através do URLCache e monitorar o progresso de download de arquivos grandes. Alternativamente, closures (manipuladores de conclusão) podem ser usados para casos simples onde o tratamento de eventos intermediários não é necessário.

Como fazer requisições com URLSession

O fluxo de trabalho básico com URLSession é o seguinte: cria-se uma configuração, a partir dela uma sessão, depois através da sessão cria-se uma tarefa com uma requisição URL, e a tarefa é iniciada. Vamos analisar um exemplo de requisição GET com um closure. Este padrão é usado na maioria dos aplicativos iOS para obter dados de APIs REST, carregar imagens e interagir com serviços em nuvem.

let url = URL(string: "https://api.example.com/users")!
let session = URLSession.shared
let task = session.dataTask(with: url) { data, response, error in
    guard let data = data, error == nil else {
        print("Error: \(error!.localizedDescription)")
        return
    }
    if let json = try? JSONSerialization.jsonObject(with: data) {
        print("JSON: \(json)")
    }
}
task.resume()

O exemplo usa URLSession.shared — um singleton com configuração .default para requisições simples. O dataTask cria uma operação assíncrona mas não a inicia — é necessário chamar resume(). O closure é executado após a conclusão da requisição e retorna data, response ou error. Para uma sessão personalizada com sua própria configuração, use o inicializador URLSession(configuration:), que permite definir políticas de cache, timeouts, conexões máximas, cabeçalhos HTTP padrão e configurações de proxy para todas as tarefas da sessão. Esta abordagem oferece controle total sobre o comportamento de rede no seu aplicativo.

Download de arquivos via URLSession

A URLSession suporta download de arquivos com capacidade de pausar e retomar, além de downloads em segundo plano. O DownloadTask salva o arquivo em um diretório temporário, e no closure de conclusão você precisa movê-lo para um local permanente.

let url = URL(string: "https://example.com/file.zip")!
let session = URLSession(configuration: .default)
let task = session.downloadTask(with: url) { location, _, _ in
    guard let location = location else { return }
    let destination = FileManager.default.temporaryDirectory
        .appendingPathComponent("file.zip")
    try? FileManager.default.moveItem(at: location, to: destination)
}
task.resume()

O parâmetro location no closure aponta para um arquivo temporário que precisa ser movido, caso contrário o sistema o excluirá após sair do closure. Para rastrear o progresso, use o delegate URLSessionDownloadDelegate com o método didWriteData, que passa o número de bytes escritos e o tamanho total do arquivo — estes dados podem ser usados para exibir uma barra de progresso na interface do usuário. Sessões em segundo plano com downloadTask permitem continuar o download mesmo após minimizar o aplicativo, e ao concluir, o sistema chama o manipulador no AppDelegate.

URLSession vs Alamofire

Alamofire é uma biblioteca Swift construída sobre a URLSession que fornece uma interface mais declarativa. A escolha entre a API nativa e o Alamofire depende da complexidade do projeto e das preferências da equipe.

Para projetos simples, a URLSession é suficiente e não adiciona dependências. O Alamofire se justifica em projetos com muitas requisições de rede, tratamento complexo de erros e necessidade de sintaxe concisa. Ambas as tecnologias compartilham a base comum URLSessionConfiguration e são compatíveis entre si. Ao escolher, considere que a URLSession é totalmente controlada pela Apple e atualizada com o iOS, enquanto o Alamofire exige que os desenvolvedores da biblioteca mantenham compatibilidade com novas versões do sistema operacional.

Exemplos de código URLSession

O Swift moderno suporta async/await, o que torna as requisições de rede mais legíveis em comparação com closures. Vamos ver a mesma requisição GET usando sintaxe assíncrona.

func fetchUsers() async throws -> [User] {
    let url = URL(string: "https://api.example.com/users")!
    let (data, _) = try await URLSession.shared.data(from: url)
    let users = try JSONDecoder().decode([User].self, from: data)
    return users
}

O método data(from:) está disponível desde o iOS 15 e macOS 12. Ele retorna uma tupla (Data, URLResponse) e lança um erro em problemas de rede. O JSONDecoder com um modelo Codable desserializa automaticamente a resposta — isso substitui o complicado JSONSerialization do exemplo anterior.

Requisição POST com corpo JSON

Para requisições POST com corpo JSON, usa-se URLRequest, onde são configurados o método, os cabeçalhos Content-Type e o corpo da requisição como Data. O Async/await torna este processo conciso e claro, e o tratamento de erros é simples através de um bloco do-catch.

func createUser(name: String) async throws -> User {
    var request = URLRequest(url: URL(string: "https://api.example.com/users")!)
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    let body = try JSONEncoder().encode(["name": name])
    request.httpBody = body
    let (data, _) = try await URLSession.shared.data(for: request)
    return try JSONDecoder().decode(User.self, from: data)
}