Retrofit: wat is het, kenmerken van de HTTP-client voor Android

Wat is Retrofit?

Retrofit — is een bibliotheek voor getypeerde interactie met REST API op het Android-platform, ontwikkeld door Square. Het biedt een declaratieve manier om HTTP-verzoeken te beschrijven via Java- of Kotlin-interfaces met annotaties, waardoor de ontwikkelaar volledig wordt bevrijd van handmatig JSON-parsen en het beheren van HTTP-verbindingen.

De bibliotheek verscheen in 2013 als alternatief voor logge oplossingen zoals AsyncTask en HttpURLConnection. In 2025 blijft Retrofit de de facto standaard voor netwerkcommunicatie in Android-apps dankzij eenvoud en typeveiligheid. Volgens een enquête van JetBrains Developer Ecosystem 2024 gebruikt meer dan 65% van de Android-ontwikkelaars Retrofit in commerciële projecten.

Het belangrijkste verschil tussen Retrofit en alternatieven — de declaratieve aanpak: de ontwikkelaar beschrijft wat te doen (welk endpoint aan te roepen, welke parameters door te geven), niet hoe het te doen (hoe de verbinding te openen, hoe InputStream te lezen, hoe JSON te parsen). Dit vermindert de hoeveelheid boilerplate-code met 60–70% in vergelijking met handmatig gebruik van HttpURLConnection.

Hoe werkt Retrofit

Werkingsprincipe van Retrofit is gebaseerd op Java dynamische proxies. Wanneer een ontwikkelaar een methode van een met annotaties gemarkeerde interface aanroept, onderschept Retrofit via het Proxy.newProxyInstance-mechanisme de aanroep en zet deze om in een HTTP-verzoek. Het hele proces vindt plaats in runtime zonder codegeneratie tijdens de compilatiefase.

Bij het maken van een Retrofit.Builder-instantie worden de basis-URL en converterfabriek opgegeven. Builder configureert OkHttpClient — stelt time-outs, interceptors, verbindingspool en cache in. De methode create(Class) genereert de implementatie van de interface en retourneert een proxy-object dat als een gewone klasse kan worden aangeroepen.

De uitvoeringsketen van een verzoek ziet er als volgt uit: annotaties extraheren de HTTP-methode, parameters worden ingevoegd in de URL of de verzoekbody, de converter serialiseert de body, OkHttp voert het verzoek uit, de converter deserialiseert het antwoord, het resultaat wordt geretourneerd in het opgegeven type. Elke fase is geïsoleerd en kan worden vervangen door een eigen implementatie, bijvoorbeeld het vervangen van OkHttpClient door MockWebServer voor testen of het wijzigen van de converter bij een API-wijziging.

Belangrijk kenmerk — Retrofit ondersteunt geen directe streaming van gegevens. Voor streaming wordt OkHttp ResponseBody gebruikt als retourtype van de interface-methode. Retrofit beheert ook niet automatisch het annuleren van verzoeken — om te annuleren moet een referentie naar Call worden bewaard en cancel() worden aangeroepen. In Kotlin met suspend-functies vindt annulering van het verzoek automatisch plaats bij annulering van de bovenliggende coroutine.

Levenscyclus van het Call-object

Call<T> — is een object dat één HTTP-verzoek vertegenwoordigt. Na uitvoering (execute of enqueue) kan Call niet opnieuw worden gebruikt — voor een herhaald verzoek moet een nieuwe Call worden gemaakt door de interface-methode aan te roepen. Dit beschermt tegen het per ongeluk twee keer verzenden van hetzelfde verzoek, wat zou kunnen leiden tot duplicatie van bewerkingen op de server.

In Kotlin worden in plaats van Call suspend-functies gebruikt die automatisch de levenscyclus van het verzoek beheren. Retrofit schakelt zelf de uitvoering naar Dispatchers.IO en retourneert het resultaat naar de coroutine. Dit verkort de code met 30–40% in vergelijking met de versie op Call en Callback.

Retrofit-annotaties voor HTTP-methoden

Annotaties — zijn het belangrijkste mechanisme voor het configureren van HTTP-verzoeken in Retrofit. Elke annotatie komt overeen met een standaard HTTP-methode en accepteert een relatief pad naar het endpoint. Retrofit ondersteunt GET, POST, PUT, DELETE, PATCH, HEAD en OPTIONS.

Annotaties van verzoekparameters

@Path vervangt de waarde in het URL-segment: @Path(id) Int id vervangt {id} in het pad. @Query voegt een query-parameter toe: @Query(page) Int page wordt ?page=5. @Body geeft een object door in de verzoekbody met automatische serialisatie via de geselecteerde converter. @Header en @Headers beheren HTTP-headers — statisch of dynamisch.

Door deze annotaties te combineren kan elk REST-endpoint worden beschreven. Bijvoorbeeld, voor het endpoint POST /api/users/{id}/posts?limit=10 zijn @POST, @Path voor id, @Query voor limit en @Body voor het doorgegeven object nodig. Retrofit stelt automatisch het juiste HTTP-verzoek samen. Daarnaast worden @Url (dynamische URL), @Field (form-encoded body), @Part en @PartMap voor multipart-verzoeken met bestanden ondersteund.

Retrofit-codevoorbeelden in Kotlin

Laten we een praktisch voorbeeld bekijken — een interface voor de GitHub API. Er wordt een Kotlin-interface gemaakt met een methode om een lijst met repositories op te halen. Data class Repo beschrijft de structuur van het JSON-antwoord.

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>
}

Na het beschrijven van de interface wordt een Retrofit-instantie gemaakt via Builder. De basis-URL, converter en OkHttpClient worden eenmalig geconfigureerd en hergebruikt via dependency injection.

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)

Antwoordverwerking met Response-wrapper

Gebruik voor flexibele verwerking van HTTP-statussen de Response<T>-wrapper. Het geeft toegang tot de antwoordcode, headers en body, zonder een uitzondering te gooien bij 4xx- en 5xx-fouten. Hiermee kunnen 404 en 500 worden verwerkt zonder 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", "Fout: ${response.code()}")
}

Converters en serialisatie in Retrofit

Converters — zijn Retrofit-componenten die verantwoordelijk zijn voor het omzetten van objecten naar HTTP-body en vice versa. Retrofit bouwt serialisatie niet in de kern — in plaats daarvan wordt een modulaire aanpak via Converter.Factory gebruikt, waarmee elke serialisatiebibliotheek kan worden aangesloten.

De populairste converter — GsonConverterFactory van Google op basis van de Gson-bibliotheek. Het is geschikt voor de meeste projecten, ondersteunt aangepaste TypeAdapter en JsonDeserializer. Gson gebruikt echter reflectie en houdt geen rekening met Kotlin null safety, wat kan leiden tot NPE bij onverwachte null-velden.

Alternatief — MoshiConverterFactory van Square: strikter met typen, met betere ondersteuning voor Kotlin (null safety, default values) en zonder reflectie. Voor projecten in pure Kotlin is optimaal — Kotlinx Serialization Converter, werkend op @Serializable-annotaties tijdens de compilatiefase. Het gebruikt geen reflectie, ondersteunt sealed class, default values en multiplatform.

De keuze van converter beïnvloedt prestaties en veiligheid van typen. Gson zonder aangepaste configuratie kan null deserialiseren naar een non-null Kotlin-veld, wat NPE veroorzaakt bij toegang. Moshi lost dit probleem op via de @Json(name)-annotatie en failOnUnknown. Kotlinx Serialization is het veiligst — het genereert code tijdens compilatie, waardoor runtime-typefouten volledig worden geëlimineerd.

Veelgemaakte fouten bij het werken met Retrofit

Het ontbreken van foutafhandeling voor HTTP in suspend-functies — het meest voorkomende probleem. Als de server 4xx of 5xx retourneert, gooit Retrofit een HttpException. Zonder try-catch zal de applicatie crashen. Het gebruik van Response<T> als retourtype lost dit probleem op, door controle van isSuccessful mogelijk te maken voordat body wordt benaderd.

Onjuiste configuratie van caching leidt tot overmatig verkeer. Retrofit cached antwoorden niet zelf — deze taak wordt opgelost door OkHttpClient via Cache. Zonder cache wordt elk verzoek volledig uitgevoerd, zelfs als de gegevens niet zijn gewijzigd. Het toevoegen van een Cache van 10 MB in OkHttpClient vermindert het verkeer met 40–60% bij herhaalde verzoeken voor dezelfde informatie.

Retrofit maken voor elk verzoek — een veelgemaakte fout van beginners. Retrofit.Builder is een resource-intensieve bewerking die het genereren van proxy-klassen in runtime omvat. De juiste praktijk — één Retrofit-instantie maken en deze hergebruiken via DI-frameworks. Hilt, Koin of Dagger zorgen voor een singleton Retrofit-instantie voor de hele app, wat geheugen bespaart en verzoeken versnelt.

Het negeren van Interceptor voor autorisatie — het vierde probleem. In plaats van handmatig de Authorization-header aan elke aanroep toe te voegen, configureert u een globale Interceptor in OkHttpClient. De Interceptor onderschept elk verzoek, voegt een Bearer-token toe, en de Authenticator verwerkt het 401-antwoord, vernieuwt het token en herhaalt het verzoek automatisch. Dit centraliseert de authenticatielogica.