Retrofit — wat is het, HTTP-bibliotheek en gebruik in applicaties

Wat is Retrofit?

Retrofit is een bibliotheek voor het uitvoeren van HTTP-verzoeken in Android-applicaties, ontwikkeld door Square. Het biedt een declaratieve benadering voor het definiëren van REST-API's via Java-interfaces met annotaties, waardoor de netwerkcommunicatiecode schoon en voorspelbaar wordt.

Het belangrijkste idee van Retrofit is dat de ontwikkelaar de API beschrijft als een interface met methoden en annotaties, en de bibliotheek genereert zelf de implementatie. Deze aanpak garandeert dat alle endpoints getypeerd zijn en fouten in URL's of parameters worden ontdekt tijdens het compileren, niet tijdens runtime.

Retrofit ondersteunt alle populaire HTTP-methoden en gegevensformaten. De bibliotheek wordt actief onderhouden door Square en de community: nieuwe versies worden regelmatig uitgebracht, en de huidige versie 2.11 ondersteunt Java 17 en Kotlin 2.0. Retrofit blijft de populairste HTTP-client voor Android.

Retrofit werkt op basis van OkHttp — een efficiënte HTTP-client eveneens van Square. Deze combinatie zorgt voor caching, het onderscheppen van verzoeken en verbindingsbeheer op het niveau van het transportprotocol. De bibliotheek ondersteunt zowel synchrone als asynchrone aanroepen.

Sinds de eerste release in 2013 heeft Retrofit verschillende grote updates ondergaan. De huidige versie Retrofit 2 is volledig herschreven met ervaring uit de eerste versie en biedt een flexibeler systeem van converters en adapters voor asynchroniteit.

De architectuur van Retrofit volgt het principe van scheiding van verantwoordelijkheden: de interface definieert alleen het API-contract, converters zorgen voor serialisatie en adapters beheren asynchroniteit. Dit maakt het mogelijk om elke component te vervangen zonder de rest van de code te wijzigen. Men kan bijvoorbeeld overstappen van Gson naar Moshi zonder de endpointdefinities te wijzigen.

Belangrijkste functionaliteiten van Retrofit

Retrofit biedt een reeks functies die vrijwel alle scenario's van netwerkcommunicatie in mobiele applicaties dekken. Het belangrijkste voordeel is de declaratieve stijl van API-definitie.

Declaratieve annotaties van endpoints

Annotaties @GET, @POST, @PUT, @PATCH, @DELETE en @HTTP maken het mogelijk de HTTP-methode en URL-sjabloon rechtstreeks in de interface te definiëren. Padparameters worden ingesteld via @Path, queryparameters via @Query en de request-body via @Body. Deze aanpak maakt de API-laag van de applicatie volledig getypeerd.

Converters voor serialisatie

Converters zetten HTTP-antwoorden om in Java-objecten en vice versa. Retrofit ondersteunt Gson, Moshi, Jackson, Protobuf en Wire. De ontwikkelaar sluit de gewenste converter aan via Converter.Factory en de bibliotheek past deze automatisch toe op alle verzoeken en antwoorden.

Adapters voor asynchroniteit

Adapters CallAdapter maken het mogelijk het retourtype van API-methoden te wijzigen. In plaats van de standaard Call kan men Observable gebruiken voor RxJava, Deferred voor Kotlin-coroutines of LiveData. Dit integreert netwerkverzoeken met de gekozen applicatiearchitectuur.

Dynamische URL's en headers

Dynamische URL's worden ingesteld via de @Url-annotatie, waardoor het endpoint tijdens runtime kan worden doorgegeven. Headers kunnen statisch worden gespecificeerd via @Headers of dynamisch via de @Header-parameter. Voor globale headers van alle verzoeken wordt een OkHttp-interceptor gebruikt die headers toevoegt aan elk uitgaand verzoek.

Hoe werkt Retrofit?

Retrofit werkt in drie fasen: het definiëren van de API-interface, het maken van een Retrofit-instantie en het uitvoeren van het verzoek. De bibliotheek genereert de implementatie van de interface tijdens runtime op basis van annotaties en converters.

Levenscyclus van een verzoek

Wanneer een API-methode wordt aangeroepen, maakt Retrofit een Request-object op basis van annotaties en argumenten. Het verzoek wordt naar OkHttp gestuurd voor uitvoering. Na ontvangst van het antwoord stuurt de bibliotheek het naar Converter.Factory voor omzetting naar het juiste type. CallAdapter wikkelt het resultaat in een asynchrone wrapper. Elke fase kan worden aangepast.

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)

Installatie en configuratie van Retrofit

Installatie van Retrofit gebeurt via Gradle — het standaard buildsysteem van Android. De bibliotheek wordt gedistribueerd via Maven Central en vereist het toevoegen van verschillende afhankelijkheden in build.gradle van het project.

Afhankelijkheden toevoegen

Voeg in het build.gradle-bestand (op moduleniveau) afhankelijkheden toe voor Retrofit, Gson-converter en OkHttp. Het wordt aanbevolen bibliotheekversies in variabelen in de root build.gradle te plaatsen voor gecentraliseerd beheer. Retrofit 2 vereist minimaal 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"
}

Retrofit-instantie maken

De Retrofit-instantie wordt gemaakt via Builder. Verplichte parameters: baseUrl en ConverterFactory. Het wordt aanbevolen een singleton te gebruiken voor Retrofit en OkHttpClient om het creëren van overbodige verbindingen te voorkomen. Het toevoegen van een logging-interceptor vereenvoudigt het debuggen van netwerkverzoeken tijdens de ontwikkeling.

Voor Kotlin-projecten wordt aanbevolen suspend-functies te gebruiken in de API-interface in plaats van Call-types. Dit vereenvoudigt de code en maakt gebruik van gestructureerde concurrency van coroutines mogelijk. Bij overstap van Call naar suspend volstaat het om het retourtype in de interface te wijzigen — de rest van de code past zich automatisch aan.

Voorbeelden van Retrofit-gebruik

Voorbeelden hieronder tonen typische scenario's van werken met Retrofit in Android-applicaties: van een eenvoudig GET-verzoek tot het uploaden van een bestand naar de server.

GET-verzoek met queryparameters

Een eenvoudig GET-verzoek met queryparameters — de basisbewerking. De @Query-annotatie voegt parameters automatisch toe aan de URL, en een suspend-functie maakt het mogelijk het verzoek vanuit een coroutine aan te roepen zonder de hoofdthread te blokkeren.

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

val users = api.getUsers(page = 1)

POST-verzoek met JSON-body

POST-verzoek met JSON-body gebruikt de @Body-annotatie voor het verzenden van een object. GsonConverterFactory serialiseert automatisch het User-object naar JSON. Kotlin-coroutines zorgen voor uitvoering van het verzoek op de achtergrond zonder Callback-interfaces.

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)

Bestand uploaden via Multipart

De @Multipart-annotatie met @Part maakt het mogelijk bestanden naar de server te uploaden. Retrofit maakt automatisch een multipart-verzoek met de juiste headers. OkHttp beheert de uploadvoortgang via RequestBody, waardoor een voortgangsindicator aan de gebruiker kan worden getoond.

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)

Foutafhandeling en interceptors in Retrofit

Foutafhandeling in Retrofit is gebaseerd op een combinatie van OkHttp-mechanismen en Kotlin-coroutines. OkHttp-interceptors maken het mogelijk verzoeken te loggen, authenticatie-headers toe te voegen en fouten af te handelen voordat ze de applicatiecode bereiken.

Voor gecentraliseerde foutafhandeling wordt vaak een wrapper rond API-aanroepen gemaakt in de vorm van een sealed class Result. Zo'n klasse bevat twee subklassen: Success met gegevens en Error met een uitzondering. ViewModel ontvangt een uniform resultaat en kan de juiste status van de gebruikersinterface weergeven zonder de foutafhandelingscode in elke functie te dupliceren.

Interceptors zijn er in twee typen: applicatie-interceptors wijzigen het verzoek vóór verzending naar de server, en netwerk-interceptors werken met het antwoord na ontvangst. Een interceptor kan bijvoorbeeld automatisch een toegangstoken vernieuwen bij ontvangst van 401 en het verzoek herhalen met het nieuwe token zonder tussenkomst van de ontwikkelaar.

Verzoeken loggen via Interceptor

Logging-interceptor HttpLoggingInterceptor — een onmisbaar hulpmiddel bij het debuggen van netwerkverzoeken. Het toont in Logcat de verzoekmethode, URL, headers, body en antwoordcode. Het logniveau kan worden geconfigureerd: BASIC voor minimale informatie, HEADERS voor headers of BODY voor volledige inhoud. In productie wordt aanbevolen BASIC te gebruiken of logging volledig uit te schakelen.

Interceptors in OkHttp zijn onderverdeeld in twee typen: applicatie-interceptors voor het wijzigen van verzoeken en netwerk-interceptors voor het werken met ruwe netwerkgegevens. De logging-interceptor toont automatisch verzoek- en antwoorddetails in Logcat.

Foutafhandeling op coroutineniveau gebeurt via try-catch rond de aanroep van een suspend-functie. Retrofit retourneert fouten als HttpException voor codes 4xx en 5xx, UnknownHostException bij geen netwerk en SocketTimeoutException bij overschrijding van de timeout. Het wordt aanbevolen sealed class Result te gebruiken voor uniforme afhandeling.