Retrofit — Type-Safe REST Client for Java and Kotlin

Introduction

Retrofit by Square turns a REST API into a Java or Kotlin interface. You declare endpoints as annotated methods and Retrofit generates the implementation, handling serialization, request construction, and response parsing automatically.

What Retrofit Does

• Maps HTTP endpoints to interface methods using annotations like @GET, @POST, @PUT, @DELETE
• Serializes and deserializes request/response bodies via pluggable converters (Gson, Moshi, Jackson, Protobuf)
• Supports both synchronous (Call) and asynchronous (suspend, RxJava, CompletableFuture) execution
• Handles path parameters, query parameters, headers, and multipart uploads declaratively
• Uses OkHttp as the underlying transport layer for connection management

Architecture Overview

Retrofit uses dynamic proxies to implement API interfaces at runtime. When a method is called, Retrofit reads its annotations to build an OkHttp Request, passes it through the OkHttp client, and then uses a Converter to deserialize the response body into the declared return type. CallAdapters bridge different async patterns like Kotlin coroutines or RxJava Observables.

Self-Hosting & Configuration

• Add via Gradle: implementation("com.squareup.retrofit2:retrofit:2.11.0")
• Include a converter: retrofit2:converter-gson or retrofit2:converter-moshi
• Configure the base URL and OkHttpClient instance in Retrofit.Builder
• Add interceptors via the underlying OkHttpClient for auth tokens or logging
• For coroutines, no extra adapter is needed since Retrofit 2.6+ supports suspend functions natively

Key Features

• Declarative API definitions reduce boilerplate to a single annotated interface
• Pluggable serialization with converters for JSON, XML, Protobuf, and custom formats
• Native Kotlin coroutine support for structured concurrency
• Composable with OkHttp interceptors for authentication, caching, and retries
• Mature ecosystem with adapters for RxJava, Guava ListenableFuture, and more

Comparison with Similar Tools

• OkHttp — lower-level; Retrofit adds the type-safe interface layer on top of OkHttp
• Ktor Client — Kotlin multiplatform HTTP client; better for KMP but lacks Retrofit's annotation model
• Feign — similar declarative style from Netflix/OpenFeign; more common in Spring Cloud ecosystems
• Spring WebClient — reactive HTTP client in Spring; tightly coupled to the Spring ecosystem

FAQ

Q: Can Retrofit be used on Android? A: Yes. Retrofit is one of the most widely used networking libraries on Android.

Q: Which serialization library should I choose? A: Moshi is recommended for Kotlin projects. Gson works well for Java-heavy codebases.

Q: Does Retrofit support file uploads? A: Yes. Use @Multipart and @Part annotations to send multipart form data.

Q: Is Retrofit thread-safe? A: Yes. Retrofit instances and service interfaces are thread-safe and can be shared.

Sources

• https://github.com/square/retrofit
• https://square.github.io/retrofit/