Retrofit : qu'est-ce que c'est, caractéristiques du client HTTP Android

Qu'est-ce que Retrofit ?

Retrofit est une bibliothèque pour l'interaction typée avec les API REST sur la plateforme Android, développée par Square. Elle offre une manière déclarative de décrire les requêtes HTTP via des interfaces Java ou Kotlin avec des annotations, éliminant complètement le besoin d'analyse manuelle du JSON et de gestion des connexions HTTP.

La bibliothèque est apparue en 2013 comme alternative aux solutions lourdes comme AsyncTask et HttpURLConnection. En 2025, Retrofit reste le standard de facto pour la communication réseau dans les applications Android grâce à sa simplicité et sa sécurité de typage. Selon l'enquête JetBrains Developer Ecosystem 2024, plus de 65% des développeurs Android utilisent Retrofit dans des projets commerciaux.

La différence clé de Retrofit par rapport aux alternatives est l'approche déclarative : le développeur décrit quoi faire (quel endpoint appeler, quels paramètres passer) plutôt que comment le faire (comment ouvrir une connexion, comment lire un InputStream, comment analyser le JSON). Cela réduit le code boilerplate de 60 à 70% par rapport à l'utilisation manuelle de HttpURLConnection.

Comment fonctionne Retrofit

Le principe de fonctionnement de Retrofit est basé sur les proxies dynamiques Java. Lorsque le développeur appelle une méthode d'une interface annotée, Retrofit intercepte l'appel via le mécanisme Proxy.newProxyInstance et le convertit en requête HTTP. Tout le processus se déroule à l'exécution sans génération de code à la compilation.

Lors de la création d'une instance Retrofit.Builder, l'URL de base et la fabrique de convertisseurs sont spécifiées. Le Builder configure OkHttpClient — définit les délais d'attente, les intercepteurs, le pool de connexions et le cache. La méthode create(Class) génère l'implémentation de l'interface, retournant un objet proxy qui peut être appelé comme une classe normale.

La chaîne d'exécution de la requête ressemble à ceci : les annotations extraient la méthode HTTP, les paramètres sont substitués dans l'URL ou le corps de la requête, le convertisseur sérialise le corps, OkHttp exécute la requête, le convertisseur désérialise la réponse, et le résultat est retourné dans le type spécifié. Chaque étape est isolée et peut être remplacée par une implémentation personnalisée, par exemple remplacer OkHttpClient par MockWebServer pour les tests ou changer de convertisseur lors d'un changement d'API.

Une caractéristique importante — Retrofit ne prend pas en charge la transmission de données en streaming directement. Pour le streaming, on utilise OkHttp ResponseBody comme type de retour de la méthode d'interface. Retrofit ne gère pas non plus l'annulation des requêtes automatiquement — pour annuler, il faut conserver une référence à Call et appeler cancel(). En Kotlin avec les fonctions suspend, l'annulation de la requête se produit automatiquement lors de l'annulation de la coroutine parente.

Cycle de vie de l'objet Call

Call<T> est un objet représentant une seule requête HTTP. Après exécution (execute ou enqueue), un Call ne peut pas être réutilisé — pour une requête répétée, un nouveau Call doit être créé en appelant la méthode de l'interface. Cela évite l'envoi accidentel de la même requête deux fois, ce qui pourrait entraîner des opérations en double sur le serveur.

En Kotlin, au lieu de Call, on utilise des fonctions suspend, qui gèrent automatiquement le cycle de vie de la requête. Retrofit bascule l'exécution sur Dispatchers.IO et retourne le résultat à la coroutine. Cela réduit le code de 30 à 40% par rapport à la version avec Call et Callback.

Annotations Retrofit pour les méthodes HTTP

Les annotations sont le mécanisme principal de configuration des requêtes HTTP dans Retrofit. Chaque annotation correspond à une méthode HTTP standard et accepte un chemin relatif vers l'endpoint. Retrofit prend en charge GET, POST, PUT, DELETE, PATCH, HEAD et OPTIONS.

Annotations des paramètres de requête

@Path substitue une valeur dans un segment d'URL : @Path("id") Int id remplace {id} dans le chemin. @Query ajoute un paramètre de requête : @Query("page") Int page se transforme en ?page=5. @Body passe un objet dans le corps de la requête avec sérialisation automatique via le convertisseur sélectionné. @Header et @Headers gèrent les en-têtes HTTP — statiques ou dynamiques.

En combinant ces annotations, on peut décrire n'importe quel endpoint REST. Par exemple, pour l'endpoint POST /api/users/{id}/posts?limit=10, on a besoin de @POST, @Path pour id, @Query pour limit et @Body pour l'objet passé. Retrofit assemble automatiquement une requête HTTP correcte. Sont également pris en charge @Url (URL dynamique), @Field (corps encodé en formulaire), @Part et @PartMap pour les requêtes multipart avec fichiers.

Exemples de code Retrofit en Kotlin

Regardons un exemple pratique — une interface pour l'API GitHub. Une interface Kotlin est créée avec une méthode pour obtenir la liste des dépôts. La classe de données Repo décrit la structure de la réponse JSON.

data class Repo(
    val name: String,
    val description: String?,
    val stargazersCount: Int,
    val forksCount: Int
)

interface GitHubApi {
    @GET("users/{user}/repos")
    suspend fun getRepos(
        @Path("user") user: String,
        @Query("sort") sort: String = "updated"
    ): List<Repo>
}

Après avoir décrit l'interface, une instance Retrofit est créée via Builder. L'URL de base, le convertisseur et OkHttpClient sont configurés une fois et réutilisés via l'injection de dépendances.

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.github.com/")
    .addConverterFactory(GsonConverterFactory.create())
    .client(OkHttpClient.Builder()
        .connectTimeout(30, TimeUnit.SECONDS)
        .build())
    .build()

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

Traitement de la réponse avec le wrapper Response

Pour un traitement flexible des codes d'état HTTP, utilisez le wrapper Response<T>. Il donne accès au code de réponse, aux en-têtes et au corps sans lever d'exception en cas d'erreurs 4xx et 5xx. Cela permet de traiter 404 et 500 sans try-catch.

interface GitHubApi {
    @GET("users/{user}/repos")
    suspend fun getRepos(
        @Path("user") user: String
    ): Response<List<Repo>>
}

val response = api.getRepos("octocat")
if (response.isSuccessful) {
    println(response.body()?.size)
} else {
    Log.e("API", "Error: ${response.code()}")
}

Convertisseurs et sérialisation dans Retrofit

Les convertisseurs sont des composants de Retrofit responsables de la conversion des objets en corps HTTP et vice versa. Retrofit n'intègre pas la sérialisation dans son noyau — il utilise plutôt une approche modulaire via Converter.Factory, permettant de brancher n'importe quelle bibliothèque de sérialisation.

Le convertisseur le plus populaire est GsonConverterFactory de Google basé sur la bibliothèque Gson. Il fonctionne pour la plupart des projets, prend en charge les TypeAdapter et JsonDeserializer personnalisés. Cependant, Gson utilise la réflexion et ne respecte pas la sécurité null de Kotlin, ce qui peut entraîner des NPE sur des champs null inattendus.

Une alternative est MoshiConverterFactory de Square : plus strict avec les types, avec un meilleur support Kotlin (sécurité null, valeurs par défaut) et sans réflexion. Pour les projets en Kotlin pur, Kotlinx Serialization Converter est optimal, fonctionnant avec les annotations @Serializable à la compilation. Il n'utilise pas la réflexion, prend en charge sealed class, les valeurs par défaut et le multiplateforme.

Le choix du convertisseur affecte les performances et la sécurité des types. Gson sans configuration personnalisée peut désérialiser null dans un champ non null de Kotlin, provoquant une NPE lors de l'accès. Moshi résout ce problème via l'annotation @Json(name) et failOnUnknown. Kotlinx Serialization est le plus sûr — il génère du code à la compilation, éliminant complètement les erreurs de type à l'exécution.

Erreurs courantes lors de l'utilisation de Retrofit

L'absence de gestion des erreurs HTTP dans les fonctions suspend est le problème le plus fréquent. Si le serveur renvoie 4xx ou 5xx, Retrofit lance HttpException. Sans try-catch, l'application plante. Utiliser Response<T> comme type de retour résout ce problème, permettant de vérifier isSuccessful avant d'accéder au body.

Une configuration incorrecte du cache entraîne un trafic excessif. Retrofit ne met pas en cache les réponses lui-même — cette tâche est assurée par OkHttpClient via Cache. Sans cache, chaque requête est exécutée complètement, même lorsque les données n'ont pas changé. L'ajout d'un cache de 10 Mo dans OkHttpClient réduit le trafic de 40 à 60% lors de requêtes répétées de la même information.

Créer Retrofit pour chaque requête est une erreur courante des débutants. Retrofit.Builder est une opération coûteuse qui implique la génération de classes proxy à l'exécution. La bonne pratique est de créer une seule instance Retrofit et de la réutiliser via des frameworks DI. Hilt, Koin ou Dagger fournissent une instance singleton de Retrofit pour toute l'application, économisant de la mémoire et accélérant les requêtes.

Ignorer Interceptor pour l'authentification est le quatrième problème. Au lieu d'ajouter manuellement l'en-tête Authorization à chaque appel, configurez un Interceptor global dans OkHttpClient. L'Interceptor intercepte chaque requête, ajoute le jeton Bearer, et l'Authenticator gère la réponse 401, renouvelant le jeton et répétant la requête automatiquement. Cela centralise la logique d'authentification.