OkHttp — qu’est-ce que c’est, fonctionnalités et architecture du client HTTP

Qu’est-ce qu’OkHttp ?

OkHttp est un client HTTP efficace pour Java, Android et Kotlin, développé par Square. La bibliothèque fournit une API de bas niveau pour exécuter des requêtes HTTP avec prise en charge de HTTP/2, SPDY, WebSocket et la récupération automatique des connexions en cas de panne réseau.

OkHttp est apparu en 2013 en réponse au besoin d’un client HTTP fiable qui résoudrait les problèmes de HttpURLConnection — absence de pool de connexions, faible prise en charge de HTTP/2 et API peu pratique. En 2025, OkHttp est utilisé au niveau système de l’Android API : OkHttp est intégré dans l’implémentation de HttpURLConnection depuis Android 4.4 (API 19).

Selon Google I/O 2024, OkHttp traite plus de 70 % de toutes les requêtes HTTP dans l’écosystème Android. Cela est possible car OkHttp sert de couche de transport pour Retrofit, Apollo GraphQL, Firebase et de nombreuses autres bibliothèques. Les développeurs bénéficient automatiquement des fonctionnalités d’OkHttp sans avoir à l’ajouter explicitement.

Comment fonctionne OkHttp

L’architecture d’OkHttp est construite sur une chaîne d’intercepteurs. Chaque requête traverse une séquence d’intercepteurs qui peuvent modifier la Request, la Response ou interrompre l’exécution. Cette architecture ressemble au modèle Chain of Responsibility et permet une extensibilité flexible.

Lorsqu’une application envoie une requête, OkHttp effectue les étapes suivantes : résout le DNS, sélectionne une connexion du pool (ou en crée une nouvelle), ouvre une poignée de main TLS (si HTTPS), envoie la requête HTTP, reçoit la réponse et la retourne à l’application. RealCall est la classe interne qui gère le cycle de vie complet d’une requête, de la création à l’achèvement.

OkHttp gère automatiquement les redirections (302, 301), réessaye les requêtes en cas de panne réseau, suit le protocole keep-alive et prend en charge la compression gzip transparente. Le développeur n’a pas besoin d’écrire de code pour ces opérations — OkHttp les effectue automatiquement en fonction des en-têtes du serveur.

Prise en charge de HTTP/2 et multiplexage

HTTP/2 permet d’envoyer plusieurs requêtes simultanément sur une seule connexion TCP, sans blocage head-of-line (caractéristique de HTTP/1.1). OkHttp utilise automatiquement HTTP/2 si le serveur le prend en charge, et bascule de manière transparente vers HTTP/1.1 si nécessaire.

Le multiplexage HTTP/2 est particulièrement important pour les applications mobiles, où la latence d’établissement de connexion (TCP + TLS) peut être de 100 – 300 ms. Au lieu de 10 connexions séquentielles, OkHttp en utilise une seule, réduisant la latence totale de 40 – 60 % sur les appareils Android typiques avec des connexions instables.

Intercepteurs OkHttp : Interceptor et NetworkInterceptor

Interceptor est une interface avec une seule méthode intercept(Chain), qui reçoit une Request, effectue des actions et retourne une Response. Il existe deux types d’intercepteurs : les intercepteurs d’application (ajoutés via addInterceptor) et les intercepteurs réseau (addNetworkInterceptor).

Les intercepteurs d’application se déclenchent avant la formation de la requête HTTP — ils voient la Request d’origine et la Response finale après toutes les transformations. Les intercepteurs réseau se déclenchent au niveau réseau : ils voient la requête après la compression gzip, l’ajout de l’en-tête Content-Length, les redirections et les tentatives. Les intercepteurs réseau ne sont pas appelés si la réponse est servie depuis le cache.

Utilisation pratique des intercepteurs

En pratique, les intercepteurs d’OkHttp résolvent trois tâches principales : l’authentification (ajout de l’en-tête Authorization), la journalisation (HttpLoggingInterceptor pour le débogage) et la tentative (répétition automatique des requêtes en cas de panne réseau). En combinant plusieurs intercepteurs, on peut construire un pipeline complet de traitement des requêtes sans dupliquer le code dans chaque appel HTTP de l’application.

L’ordre d’ajout des intercepteurs a de l’importance : l’Interceptor ajouté en premier s’exécute en premier à l’entrée et en dernier à la sortie. Pour NetworkInterceptor, l’ordre est déterminé par la pile réseau. Ordre recommandé : AuthInterceptor (ajoute le token), LoggingInterceptor (journalise la requête), RetryInterceptor (réessaye en cas d’échec).

Journalisation via HttpLoggingInterceptor

Pour déboguer les requêtes réseau, on utilise HttpLoggingInterceptor — un intercepteur prêt à l’emploi de Square. Il journalise la méthode, l’URL, les en-têtes et le corps de la requête et de la réponse. Niveaux de journalisation : BASIC (méthode + URL + code), HEADERS (avec en-têtes) et BODY (requête et réponse complètes). BODY est utile pendant le développement mais est désactivé en production pour des raisons de sécurité et de performance.

Exemples de code OkHttp en Kotlin

Examinons une requête GET de base avec OkHttp. D’abord, un OkHttpClient est créé — un objet lourd qui est créé une fois et réutilisé. Ensuite, une Request est formée avec une URL, et la requête est exécutée de manière synchrone via execute ou asynchrone via enqueue.

val client = OkHttpClient.Builder()
    .connectTimeout(15, TimeUnit.SECONDS)
    .readTimeout(15, TimeUnit.SECONDS)
    .build()

val request = Request.Builder()
    .url("https://api.github.com/users/octocat")
    .header("Accept", "application/vnd.github.v3+json")
    .build()

val response = client.newCall(request).execute()
println(response.body()?.string())

Pour l’exécution asynchrone, la méthode enqueue est utilisée, qui accepte un Callback. OkHttp exécute la requête dans un thread d’arrière-plan et retourne le résultat dans le callback sur le même thread. Pour basculer vers le thread principal d’Android, utilisez Handler ou les coroutines.

client.newCall(request).enqueue(object : Callback {
    override fun onFailure(
        call: Call, e: IOException
    ) {
        println("Échec de la requête : ${e.message}")
    }

    override fun onResponse(
        call: Call, response: Response
    ) {
        println(response.body()?.string())
    }
})

Ajout d’un intercepteur pour l’authentification

Un Interceptor personnalisé ajoute un token Bearer à chaque requête. L’intercepteur vérifie la présence de l’en-tête Authorization, et si le token n’est pas encore défini, l’ajoute depuis le stockage. Sur une réponse 401, l’intercepteur peut rafraîchir le token via Authenticator.

class AuthInterceptor(
    private val tokenProvider: () -> String?
) : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response {
        val originalRequest = chain.request()
        val token = tokenProvider.invoke()
        val request = originalRequest.newBuilder()
            .header("Authorization", "Bearer $token")
            .build()
        return chain.proceed(request)
    }
}

Pool de connexions et mise en cache dans OkHttp

Pool de connexions (ConnectionPool) est une optimisation clé d’OkHttp qui permet de réutiliser les connexions TCP pour plusieurs requêtes. Au lieu de créer un nouveau socket pour chaque requête, OkHttp stocke jusqu’à 5 connexions inactives (par défaut) pendant 5 minutes, réduisant la latence de 30 – 70 % pour les requêtes répétées au même hôte.

La mise en cache des réponses est implémentée via la classe Cache. Pour activer le cache, il suffit de spécifier le répertoire et la taille maximale dans OkHttpClient.Builder. OkHttp met automatiquement en cache les réponses GET selon les en-têtes Cache-Control, Expires et ETag, retournant les données en cache sans requête réseau si elles ne sont pas obsolètes.

val cacheDir = File(context.cacheDir, "http-cache")
val cache = Cache(cacheDir, 10L * 1024 * 1024)

val client = OkHttpClient.Builder()
    .cache(cache)
    .connectionPool(ConnectionPool(5, 5, TimeUnit.MINUTES))
    .build()

Une configuration appropriée du pool et du cache est particulièrement importante pour les applications avec des requêtes fréquentes — fils d’actualité, chats, mises à jour de données. Sans pool, chaque connexion TCP nécessite une poignée de main à trois voies (SYN, SYN-ACK, ACK) et potentiellement une poignée de main TLS (2 – 3 allers-retours), ajoutant 100 – 500 ms à chaque requête.

OkHttp prend également en charge WebSocket via la classe RealWebSocket. Une connexion WebSocket est établie via une poignée de main HTTP (101 Switching Protocols) puis bascule vers un protocole bidirectionnel. OkHttp envoie automatiquement des trames ping pour maintenir la connexion active et se reconnecte en cas de déconnexion. Le WebSocket d’OkHttp est compatible avec des points d’accès standard comme wss://echo.websocket.org.

Erreurs courantes lors de l’utilisation d’OkHttp

Créer OkHttpClient pour chaque requête est l’erreur la plus courante. OkHttpClient contient un pool de connexions, un cache et un pool de threads. Créer une nouvelle instance pour chaque requête non seulement gaspille de la mémoire mais aussi perd l’avantage de la réutilisation des connexions. OkHttpClient doit être un singleton via un conteneur DI.

Ignorer la fermeture de Response.body() entraîne des fuites de ressources. ResponseBody contient un InputStream qui doit être fermé après la lecture. Si vous utilisez body().string() ou body().bytes(), OkHttp ferme le flux automatiquement, mais lors de la lecture de body().byteStream() ou body().charStream(), un appel explicite close() dans un bloc finally est nécessaire.

Absence de gestion du Timeout est un autre problème. Par défaut, OkHttp a un connectTimeout de 10 secondes, un readTimeout de 10 secondes et un writeTimeout de 10 secondes. Pour les applications mobiles avec des connexions instables, il est recommandé de définir connectTimeout entre 15 – 30 secondes et readTimeout entre 15 – 30 secondes, sinon l’utilisateur attendra trop longtemps avec un signal faible.