Retrofit — qu'est-ce que c'est, bibliothèque HTTP et utilisation dans les applications

Qu'est-ce que Retrofit ?

Retrofit est une bibliothèque pour effectuer des requêtes HTTP dans les applications Android, développée par Square. Elle fournit une approche déclarative pour définir des API REST via des interfaces Java avec des annotations, rendant le code d'interaction réseau propre et prévisible.

L'idée principale de Retrofit est que le développeur décrit l'API comme une interface avec des méthodes et des annotations, et la bibliothèque génère l'implémentation automatiquement. Cette approche garantit que tous les endpoints sont typés et que les erreurs dans les URL ou paramètres sont détectées à la compilation, pas à l'exécution.

Retrofit prend en charge toutes les méthodes HTTP et formats de données populaires. La bibliothèque est activement maintenue par Square et la communauté : les nouvelles versions sortent régulièrement, et la version actuelle 2.11 inclut la prise en charge de Java 17 et Kotlin 2.0. Retrofit reste le client HTTP le plus populaire pour Android.

Retrofit fonctionne au-dessus d'OkHttp, un client HTTP efficace également de Square. Cette combinaison offre la mise en cache, l'interception des requêtes et la gestion des connexions au niveau du protocole de transport. La bibliothèque prend en charge les appels synchrones et asynchrones.

Depuis sa première version en 2013, Retrofit a connu plusieurs mises à jour majeures. La version actuelle Retrofit 2 a été complètement réécrite sur la base de l'expérience de la première version et offre un système plus flexible de convertisseurs et d'adaptateurs pour l'asynchronie.

L'architecture de Retrofit suit le principe de séparation des responsabilités : l'interface définit uniquement le contrat API, les convertisseurs gèrent la sérialisation et les adaptateurs gèrent l'asynchronie. Cela permet de remplacer n'importe quel composant sans modifier le reste du code. Par exemple, vous pouvez passer de Gson à Moshi sans modifier les définitions des endpoints.

Principales fonctionnalités de Retrofit

Retrofit fournit un ensemble de fonctionnalités qui couvrent pratiquement tous les scénarios d'interaction réseau dans les applications mobiles. L'avantage clé est le style déclaratif de définition d'API.

Annotations déclaratives des endpoints

Les annotations @GET, @POST, @PUT, @PATCH, @DELETE et @HTTP permettent de spécifier la méthode HTTP et le modèle d'URL directement dans l'interface. Les paramètres de chemin sont définis via @Path, les paramètres de requête via @Query et le corps de la requête via @Body. Cette approche rend la couche API de l'application entièrement typée.

Convertisseurs pour la sérialisation

Les convertisseurs transforment les réponses HTTP en objets Java et vice versa. Retrofit prend en charge Gson, Moshi, Jackson, Protobuf et Wire. Le développeur connecte le convertisseur nécessaire via Converter.Factory, et la bibliothèque l'applique automatiquement à toutes les requêtes et réponses.

Adaptateurs pour l'asynchronie

Les adaptateurs CallAdapter permettent de modifier le type de retour des méthodes API. Au lieu du Call standard, on peut utiliser Observable pour RxJava, Deferred pour les coroutines Kotlin ou LiveData. Cela intègre les requêtes réseau avec l'architecture d'application choisie.

URL dynamiques et en-têtes

Les URL dynamiques sont définies via l'annotation @Url, permettant de passer l'endpoint à l'exécution. Les en-têtes peuvent être spécifiés statiquement via @Headers ou dynamiquement via le paramètre @Header. Pour les en-têtes globaux de toutes les requêtes, on utilise un intercepteur OkHttp qui ajoute des en-têtes à chaque requête sortante.

Comment fonctionne Retrofit ?

Retrofit fonctionne en trois étapes : définir l'interface API, créer une instance Retrofit et exécuter la requête. La bibliothèque génère l'implémentation de l'interface à l'exécution sur la base des annotations et des convertisseurs.

Cycle de vie d'une requête

Lorsqu'une méthode API est appelée, Retrofit crée un objet Request basé sur les annotations et les arguments. La requête est transmise à OkHttp pour exécution. Après réception de la réponse, la bibliothèque la transmet à Converter.Factory pour transformation dans le type requis. CallAdapter enveloppe le résultat dans un wrapper asynchrone. Chaque étape peut être personnalisée.

interface ApiService {
    @GET("users/{id}")
    suspend fun getUser(@Path("id") id: Int): User
}

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .addConverterFactory(GsonConverterFactory.create())
    .build()

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

Installation et configuration de Retrofit

L'installation de Retrofit se fait via Gradle, le système de construction standard d'Android. La bibliothèque est distribuée via Maven Central et nécessite l'ajout de plusieurs dépendances dans le build.gradle du projet.

Ajout des dépendances

Dans le fichier build.gradle (au niveau du module), ajoutez les dépendances pour Retrofit, le convertisseur Gson et OkHttp. Il est recommandé d'extraire les versions des bibliothèques dans des variables dans le build.gradle racine pour une gestion centralisée. Retrofit 2 nécessite au minimum Android API 21.

dependencies {
    implementation "com.squareup.retrofit2:retrofit:2.11.0"
    implementation "com.squareup.retrofit2:converter-gson:2.11.0"
    implementation "com.squareup.okhttp3:okhttp:4.12.0"
    implementation "com.squareup.okhttp3:logging-interceptor:4.12.0"
}

Création d'une instance Retrofit

Une instance Retrofit est créée via Builder. Paramètres obligatoires : baseUrl et ConverterFactory. Il est recommandé d'utiliser un singleton pour Retrofit et OkHttpClient pour éviter de créer des connexions redondantes. L'ajout d'un logging-interceptor simplifie le débogage des requêtes réseau pendant le développement.

Pour les projets Kotlin, il est recommandé d'utiliser des fonctions suspend dans l'interface API au lieu des types Call. Cela simplifie le code et permet d'utiliser la concurrence structurée des coroutines. Lors du passage de Call à suspend, il suffit de modifier le type de retour dans l'interface — le reste du code s'adapte automatiquement.

Exemples d'utilisation de Retrofit

Les exemples ci-dessous montrent des scénarios typiques de travail avec Retrofit dans les applications Android : d'une simple requête GET au téléchargement d'un fichier vers le serveur.

Requête GET avec paramètres de requête

Une requête GET simple avec des paramètres de chaîne de requête est une opération de base. L'annotation @Query ajoute automatiquement les paramètres à l'URL, et la fonction suspend permet d'appeler la requête depuis une coroutine sans bloquer le thread principal.

interface UserApi {
    @GET("users")
    suspend fun getUsers(
        @Query("page") page: Int,
        @Query("limit") limit: Int = 20
    ): List<User>
}

val users = api.getUsers(page = 1)

Requête POST avec corps JSON

Une requête POST avec un corps JSON utilise l'annotation @Body pour passer l'objet. GsonConverterFactory sérialise automatiquement l'objet User en JSON. Les coroutines Kotlin assurent l'exécution de la requête dans un thread d'arrière-plan sans interfaces Callback.

interface UserApi {
    @POST("users")
    suspend fun createUser(@Body user: User): User
}

val user = User(name = "Anna Ivanova", email = "anna@example.com")
val created = api.createUser(user)

Téléchargement de fichier via Multipart

L'annotation @Multipart avec @Part permet de télécharger des fichiers vers le serveur. Retrofit forme automatiquement une requête multipart avec les en-têtes nécessaires. OkHttp gère la progression du téléchargement via RequestBody, permettant d'afficher un indicateur à l'utilisateur.

interface FileApi {
    @Multipart
    @POST("upload")
    suspend fun uploadImage(
        @Part file: MultipartBody.Part
    ): UploadResponse
}

val body = "image.jpg".toRequestBody("image/jpeg".toMediaTypeOrNull())
val part = MultipartBody.Part.createFormData("file", "image.jpg", body)

Gestion des erreurs et intercepteurs dans Retrofit

La gestion des erreurs dans Retrofit repose sur une combinaison de mécanismes OkHttp et de coroutines Kotlin. Les intercepteurs OkHttp permettent de journaliser les requêtes, d'ajouter des en-têtes d'authentification et de traiter les erreurs avant qu'elles n'atteignent le code applicatif.

Pour une gestion centralisée des erreurs, on crée souvent un wrapper autour des appels API sous forme de classe scellée Result. Cette classe a deux sous-classes : Success avec les données et Error avec une exception. Le ViewModel reçoit un résultat unifié et peut afficher l'état d'interface utilisateur correspondant sans dupliquer le code de gestion d'erreurs dans chaque fonction.

Les intercepteurs sont de deux types : les intercepteurs d'application modifient la requête avant envoi au serveur, et les intercepteurs réseau travaillent avec la réponse après réception. Par exemple, un intercepteur peut actualiser automatiquement le jeton d'accès lors de la réception d'un 401 et répéter la requête avec le nouveau jeton sans intervention du développeur.

Journalisation des requêtes via Interceptor

L'intercepteur de journalisation HttpLoggingInterceptor est un outil indispensable pour déboguer les requêtes réseau. Il affiche dans Logcat la méthode de requête, l'URL, les en-têtes, le corps et le code de réponse. Le niveau de journalisation peut être configuré : BASIC pour les informations minimales, HEADERS pour les en-têtes ou BODY pour le contenu complet. En production, il est recommandé d'utiliser BASIC ou de désactiver complètement la journalisation.

Les intercepteurs dans OkHttp se divisent en deux types : les intercepteurs d'application pour modifier la requête et les intercepteurs réseau pour travailler avec les données réseau brutes. L'intercepteur de journalisation affiche automatiquement les détails de la requête et de la réponse dans Logcat.

La gestion des erreurs au niveau des coroutines s'effectue via try-catch autour de l'appel de la fonction suspend. Retrofit renvoie les erreurs sous forme d'HttpException pour les codes 4xx et 5xx, UnknownHostException en l'absence de réseau et SocketTimeoutException en cas de dépassement du délai d'attente. Il est recommandé d'utiliser une classe scellée Result pour un traitement unifié.