# Retrofit — Type-Safe REST Client for Java and Kotlin

> A type-safe HTTP client by Square that turns REST API definitions into callable Java/Kotlin interfaces.

## Install

Save as a script file and run:

# Retrofit — Type-Safe REST Client for Java and Kotlin

## Quick Use
```kotlin
interface GitHubService {
    @GET("users/{user}/repos")
    suspend fun listRepos(@Path("user") user: String): List<Repo>
}

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.github.com/")
    .addConverterFactory(GsonConverterFactory.create())
    .build()
val service = retrofit.create(GitHubService::class.java)
```

## 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/

---
Source: https://tokrepo.com/en/workflows/04c36937-433f-11f1-9bc6-00163e2b0d79
Author: Script Depot