Retrofit (software)

Retrofit (software)
Name	Retrofit
Developer	Square, Inc.
Initial release	2013
Latest release	2.x / 3.x series
Repo	square/retrofit
Programming language	Java, Kotlin
Operating system	Cross-platform (JVM, Android)
License	Apache License 2.0

Retrofit (software) Retrofit is a type-safe HTTP client library for the Java and Kotlin ecosystems, originally developed by Square, Inc. It provides declarative API binding and runtime request generation for RESTful services, facilitating interactions with web services such as those offered by Google, Amazon, Microsoft, Facebook, and Twitter. Retrofit is widely used across projects involving Android (operating system), Spring Framework, Kotlin, Maven, and Gradle build systems.

Overview

Retrofit emerged from the same Square team behind libraries like OkHttp, Picasso (software), Okio, and Wire (protocol buffer), aiming to simplify client-side HTTP integration for platforms including Android (operating system), Java SE, and Kotlin. It leverages annotations influenced by frameworks such as JAX-RS, Retrofit's predecessor, and patterns used in Apache HTTPClient integrations. Retrofit commonly interoperates with serialization libraries and converters such as Gson, Jackson (software), Moshi, Protocol Buffers, and Kotlinx.serialization, and integrates with network stacks including OkHttp, Apache HttpClient, and Java HTTP Client (HttpClient).

Architecture and Components

Retrofit's core architecture composes several cooperating parts: a declarative interface definition layer, a request/response conversion layer, an HTTP client transport layer, and an adapter layer for call types. The declarative layer uses Java and Kotlin annotations similar to JAX-RS, AndroidAnnotations, and patterns in Spring MVC controllers. The conversion layer supports plug-ins from Gson, Moshi, Jackson (software), Kotlinx.serialization, and Protobuf (Google). The transport layer most frequently delegates to OkHttp, which in turn interacts with Okio and the Java networking stack. The adapter layer enables integrations with asynchronous frameworks and reactive libraries such as RxJava, Kotlin Coroutines, CompletableFuture, and Project Reactor.

Key classes and interfaces include the builder pattern inspired by Effective Java and libraries like OkHttpClient, which construct instances via factory methods and dependency injection patterns used by Dagger (software), Hilt (software), and Guice (software). Converters and call adapters follow extension points similar to plugins in Maven and Gradle.

Features and Functionality

Retrofit provides features including declarative endpoint definitions, dynamic URL resolution, header and parameter annotations, request body serialization, multipart uploads, and streaming downloads. It supports synchronous calls, asynchronous callbacks, reactive streams via RxJava and Project Reactor, and coroutine support for Kotlin with structured concurrency concepts influenced by Kotlin Coroutines. Error handling integrates with exception models from Java SE and patterns used in Spring Framework's RestTemplate. Interceptors borrow middleware concepts used by OkHttp and echo approaches from Express.js and ASP.NET Core middleware pipelines.

Advanced functionality includes support for HTTP/2 and TLS features present in OkHttp and BoringSSL ecosystems, connection pooling strategies referenced in Apache HTTPClient and Netty, and instrumentation hooks compatible with tracing systems like OpenTelemetry, Zipkin, and Jaeger.

Usage and Integration

Developers declare interfaces annotated with HTTP method annotations, influenced by JAX-RS and Feign (software), and create Retrofit instances via builders similar to patterns in OkHttpClient and HttpClient (Java 11). Retrofit integrates with dependency injection frameworks such as Dagger (software), Hilt (software), Spring Framework, and Guice (software), and is commonly configured in build systems including Gradle, Maven, and Bazel. In mobile stacks, integrations exist with Android Jetpack, WorkManager, Room (software), and image libraries like Picasso (software) and Glide (software). Retrofit supports testing with JUnit, Mockito, Robolectric, and HTTP stubbing tools such as MockWebServer and WireMock.

Adapters allow Retrofit to produce return types consumed by RxJava, Kotlin Coroutines, CompletableFuture, and reactive endpoints exposed by Spring WebFlux.

Performance and Scalability

Retrofit delegates network I/O to optimized clients like OkHttp and benefits from HTTP/2 multiplexing, connection pooling, and socket optimizations familiar from Netty and Apache HTTPClient. Performance characteristics depend on serialization choices—Gson and Jackson (software) versus Moshi or binary formats like Protocol Buffers—and on thread models used (callback threads, RxJava schedulers, or Kotlin Coroutines dispatchers). Retrofit scales horizontally in microservice architectures alongside platform components like Kubernetes, Docker, Istio, and works with load balancing strategies from Envoy and HAProxy. Profiling and tracing commonly utilize OpenTelemetry, Zipkin, and Jaeger alongside JVM tooling such as VisualVM, YourKit, and JProfiler.

Adoption and Examples

Retrofit is widely adopted in Android applications by companies like Square, Inc., Twitter, Pinterest, Uber Technologies, and Netflix, and in JVM services that integrate with ecosystems from Google Cloud Platform, Amazon Web Services, and Microsoft Azure. Open-source projects and samples include integrations with Firebase, GraphQL backends via adapters influenced by Apollo (software), and API clients for services like GitHub, Stripe, Slack, and Trello. Retrofit appears in tutorials and books alongside Android Developers guides, Kotlinlang.org resources, and community posts on Stack Overflow and GitHub.

Security and Limitations

Security considerations for Retrofit center on TLS configuration, certificate pinning patterns used in OkHttp and BoringSSL, secure serialization to avoid vulnerabilities noted in Jackson (software) and Gson, and safe header handling with OAuth flows from OAuth 2.0 and identity providers such as Auth0 and Okta. Limitations include reliance on the underlying HTTP client for low-level networking behavior, potential performance impacts from reflection-based converters versus code-generated serializers like Kotlinx.serialization or AutoValue, and constrained control over connection management compared to servers like Netty. Runtime errors from misconfigured converters or adapters are addressed via testing with JUnit and stubbing with MockWebServer.

Category:HTTP client libraries