Project Overview
Retrofit is a type-safe HTTP client for Android and the JVM from Square. You define a Java or Kotlin interface, annotate methods with HTTP metadata, and let Retrofit turn those declarations into runtime API calls. You can use it for REST-style service integration, authenticated mobile API calls, and JVM service-to-service clients where you want strongly typed request and response models.
Retrofit is mature and focused. You get a clear abstraction for endpoint contracts, while your transport details still sit on top of OkHttp. That balance is useful when your team wants readable API boundaries without giving up lower-level network control.
Key Challenges Addressed
You often lose time when API code spreads raw URL building, serialization choices, and response parsing logic across many call sites. Retrofit targets that by centralizing endpoint contracts in annotated interfaces.
- Interface-first API definitions keep request shape, path parameters, headers, and body models in one place.
- Converter factories let you standardize JSON or other payload formats across your whole client layer.
- Call adapter factories let you align execution style with your stack (for example synchronous calls, callbacks, or coroutine/Rx integrations).
- OkHttp integration gives your team interceptors, connection pooling, TLS config, and retry controls at the transport layer.
Getting Started
You can start with a small interface and one Retrofit builder. A minimal workflow is to pick a converter, create a service interface, and execute one request.
interface RepoApi {
@GET("repos/{owner}/{repo}")
suspend fun repo(
@Path("owner") owner: String,
@Path("repo") repo: String
): RepoDto
}
val retrofit = Retrofit.Builder()
.baseUrl("https://api.github.com/")
.addConverterFactory(MoshiConverterFactory.create())
.build()
val api = retrofit.create(RepoApi::class.java)
val result = api.repo("square", "retrofit")
You will hit sharp edges quickly if your base URL format is wrong, your converter does not match API payload shape, or your threading model is inconsistent with your chosen call adapter.
Features and Use Cases
Retrofit gives your team a strong contract layer over HTTP.
- Annotated endpoints (
@GET,@POST,@Path,@Query,@Body) for readable API contracts. - Pluggable converters for JSON and other encodings.
- Pluggable call adapters so your app/service execution model stays consistent.
- Per-method and global headers for auth and content negotiation.
- Tight OkHttp interoperability for interceptors, logging, and connection behavior.
Common implementation patterns include Android app data layers, backend integrations in JVM services, and shared API modules where your team keeps endpoint definitions versioned and reviewed like any other interface contract.
Ecosystem and Dependencies
Retrofit depends on OkHttp for transport. That means your existing OkHttp interceptors, certificate pinning strategy, and timeout defaults carry over cleanly.
For serialization, you typically pair Retrofit with converters such as Moshi or Gson, based on your current model stack. For async style, you use call adapters aligned with your runtime choices so API calls fit naturally into your existing control flow.
When you compare alternatives, related projects you may evaluate include OkHttp, Ktor, Feign, Apache HttpComponents Client, and Volley.
Architectural Overview
Retrofit has a layered architecture:
- Interface contracts define endpoints and parameter mapping.
- Retrofit runtime parses annotations and builds request metadata.
- Converter layer serializes request bodies and deserializes responses.
- Call adapter layer maps raw calls into your chosen execution abstraction.
- OkHttp executes network I/O and connection management.
This design matters because you can swap serialization or async models without rewriting endpoint interfaces, and you can harden transport behavior in one place through OkHttp configuration.
Pros and Cons
- Pros: You get clean, versionable API contracts that are easy to review and test.
- Pros: Converter and call adapter extensions keep your core client layer adaptable as your stack changes.
- Pros: OkHttp integration gives strong operational control for mobile and server JVM workloads.
- Cons: Annotation-driven interfaces can hide runtime mapping errors until integration tests run.
- Cons: Complex API shapes can require careful converter configuration and custom adapters.
- Cons: If your team needs a full framework-level HTTP stack with server/client symmetry, Retrofit can feel narrower than broader platforms.
Comparison and Alternatives
GitHub stars
Weekly star gains
Full metrics details
GitHub GraphQL current stargazer cohort, reconstructed from starredAt events and totalCount retrieved in one stable pagination walk. GitHub does not expose historical unstar events, so this is not an exact ledger of past star counts.
Retrofit
GitHub GraphQL current stargazer cohort, reconstructed from starredAt events and totalCount retrieved in one stable pagination walk. GitHub does not expose historical unstar events, so this is not an exact ledger of past star counts.
180 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
OkHttp
GitHub GraphQL current stargazer cohort, reconstructed from starredAt events and totalCount retrieved in one stable pagination walk. GitHub does not expose historical unstar events, so this is not an exact ledger of past star counts.
180 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
Ktor
GitHub GraphQL current stargazer cohort, reconstructed from starredAt events and totalCount retrieved in one stable pagination walk. GitHub does not expose historical unstar events, so this is not an exact ledger of past star counts.
41 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
Feign
GitHub GraphQL current stargazer cohort, reconstructed from starredAt events and totalCount retrieved in one stable pagination walk. GitHub does not expose historical unstar events, so this is not an exact ledger of past star counts.
43 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
Apache HttpComponents Client
GitHub GraphQL current stargazer cohort, reconstructed from starredAt events and totalCount retrieved in one stable pagination walk. GitHub does not expose historical unstar events, so this is not an exact ledger of past star counts.
42 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
Issues opened
Weekly total
Full metrics details
GitHub API observation. Historical values render only when the source provides a real observation for that day.
Retrofit
GitHub API observation. Historical values render only when the source provides a real observation for that day.
178 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
OkHttp
GitHub API observation. Historical values render only when the source provides a real observation for that day.
36 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
Issues closed
Weekly total
Full metrics details
GitHub Search issue totals queried for exact UTC days; rolling values are sums of proven daily counts.
Retrofit
GitHub Search issue totals queried for exact UTC days; rolling values are sums of proven daily counts.
178 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
OkHttp
GitHub Search issue totals queried for exact UTC days; rolling values are sums of proven daily counts.
36 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
Pull requests opened
Weekly total
Full metrics details
GitHub API observation. Historical values render only when the source provides a real observation for that day.
Retrofit
GitHub API observation. Historical values render only when the source provides a real observation for that day.
178 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
OkHttp
GitHub API observation. Historical values render only when the source provides a real observation for that day.
36 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
Pull requests closed
Weekly total
Full metrics details
GitHub Search pull-request totals queried for exact UTC days; rolling values are sums of proven daily counts.
Retrofit
GitHub Search pull-request totals queried for exact UTC days; rolling values are sums of proven daily counts.
178 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
OkHttp
GitHub Search pull-request totals queried for exact UTC days; rolling values are sums of proven daily counts.
36 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
Pull requests merged
Weekly total
Full metrics details
GitHub API observation. Historical values render only when the source provides a real observation for that day.
Retrofit
GitHub API observation. Historical values render only when the source provides a real observation for that day.
178 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
OkHttp
GitHub API observation. Historical values render only when the source provides a real observation for that day.
36 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
Open/closed pull request ratio
Weekly average
Full metrics details
GitHub Search pull-request totals queried for exact UTC days; rolling values are sums of proven daily counts.
Retrofit
GitHub Search pull-request totals queried for exact UTC days; rolling values are sums of proven daily counts.
180 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
OkHttp
GitHub Search pull-request totals queried for exact UTC days; rolling values are sums of proven daily counts.
180 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
Ktor
GitHub Search pull-request totals queried for exact UTC days; rolling values are sums of proven daily counts.
41 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
Feign
GitHub Search pull-request totals queried for exact UTC days; rolling values are sums of proven daily counts.
43 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
Apache HttpComponents Client
GitHub Search pull-request totals queried for exact UTC days; rolling values are sums of proven daily counts.
42 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
Open/closed issues ratio
Weekly average
Full metrics details
GitHub Search issue totals queried for exact UTC days; rolling values are sums of proven daily counts.
Retrofit
GitHub Search issue totals queried for exact UTC days; rolling values are sums of proven daily counts.
180 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
OkHttp
GitHub Search issue totals queried for exact UTC days; rolling values are sums of proven daily counts.
180 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
Ktor
GitHub Search issue totals queried for exact UTC days; rolling values are sums of proven daily counts.
41 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
Feign
GitHub Search issue totals queried for exact UTC days; rolling values are sums of proven daily counts.
43 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
Apache HttpComponents Client
GitHub Search issue totals queried for exact UTC days; rolling values are sums of proven daily counts.
42 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
Releases
Weekly total
Full metrics details
GitHub release published_at events bucketed by UTC day; drafts are excluded.
Retrofit
GitHub release published_at events bucketed by UTC day; drafts are excluded.
180 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
OkHttp
GitHub release published_at events bucketed by UTC day; drafts are excluded.
180 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
Ktor
GitHub release published_at events bucketed by UTC day; drafts are excluded.
41 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
Feign
GitHub release published_at events bucketed by UTC day; drafts are excluded.
43 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
Apache HttpComponents Client
GitHub release published_at events bucketed by UTC day; drafts are excluded.
42 observed daily rows. Missing days are not fabricated.
| Date | Value |
|---|
Hotness score
Weekly average
Full metrics details
Derived only from GitHub GraphQL starredAt events after daily star totals are reconciled.
Retrofit
Derived only from GitHub GraphQL starredAt events after daily star totals are reconciled.
180 observed daily rows. Missing days are not fabricated.
Per-day formula: 0.40 × Hot today + 0.40 × Hot week + 0.20 × Breakout.
- Same-day multiplier = stars 1d ÷ max(1, stars 7d ÷ 7)
- Weekly multiplier = stars 7d ÷ max(1, stars 30d ÷ 30 × 7)
- Fortnight multiplier = stars 14d ÷ max(1, stars 90d ÷ 90 × 14)
- Hot today = clamp(70 × log-scale(stars 1d, 1000) + 30 × breakout-scale(same-day, 4))
- Hot week = clamp(75 × log-scale(stars 7d, 5000) + 25 × breakout-scale(weekly, 3))
- Breakout = clamp(35 × breakout-scale(same-day, 4) + 40 × breakout-scale(weekly, 3) + 25 × breakout-scale(fortnight, 2.5))
| Date | Stars | Stars 1d | Stars 7d | Stars 14d | Stars 30d | Stars 90d | Same-day multiplier | Weekly multiplier | Fortnight multiplier | Hot today | Hot week | Breakout | Stored score |
|---|
OkHttp
Derived only from GitHub GraphQL starredAt events after daily star totals are reconciled.
180 observed daily rows. Missing days are not fabricated.
Per-day formula: 0.40 × Hot today + 0.40 × Hot week + 0.20 × Breakout.
- Same-day multiplier = stars 1d ÷ max(1, stars 7d ÷ 7)
- Weekly multiplier = stars 7d ÷ max(1, stars 30d ÷ 30 × 7)
- Fortnight multiplier = stars 14d ÷ max(1, stars 90d ÷ 90 × 14)
- Hot today = clamp(70 × log-scale(stars 1d, 1000) + 30 × breakout-scale(same-day, 4))
- Hot week = clamp(75 × log-scale(stars 7d, 5000) + 25 × breakout-scale(weekly, 3))
- Breakout = clamp(35 × breakout-scale(same-day, 4) + 40 × breakout-scale(weekly, 3) + 25 × breakout-scale(fortnight, 2.5))
| Date | Stars | Stars 1d | Stars 7d | Stars 14d | Stars 30d | Stars 90d | Same-day multiplier | Weekly multiplier | Fortnight multiplier | Hot today | Hot week | Breakout | Stored score |
|---|
Ktor
Derived only from GitHub GraphQL starredAt events after daily star totals are reconciled.
41 observed daily rows. Missing days are not fabricated.
Per-day formula: 0.40 × Hot today + 0.40 × Hot week + 0.20 × Breakout.
- Same-day multiplier = stars 1d ÷ max(1, stars 7d ÷ 7)
- Weekly multiplier = stars 7d ÷ max(1, stars 30d ÷ 30 × 7)
- Fortnight multiplier = stars 14d ÷ max(1, stars 90d ÷ 90 × 14)
- Hot today = clamp(70 × log-scale(stars 1d, 1000) + 30 × breakout-scale(same-day, 4))
- Hot week = clamp(75 × log-scale(stars 7d, 5000) + 25 × breakout-scale(weekly, 3))
- Breakout = clamp(35 × breakout-scale(same-day, 4) + 40 × breakout-scale(weekly, 3) + 25 × breakout-scale(fortnight, 2.5))
| Date | Stars | Stars 1d | Stars 7d | Stars 14d | Stars 30d | Stars 90d | Same-day multiplier | Weekly multiplier | Fortnight multiplier | Hot today | Hot week | Breakout | Stored score |
|---|
Feign
Derived only from GitHub GraphQL starredAt events after daily star totals are reconciled.
43 observed daily rows. Missing days are not fabricated.
Per-day formula: 0.40 × Hot today + 0.40 × Hot week + 0.20 × Breakout.
- Same-day multiplier = stars 1d ÷ max(1, stars 7d ÷ 7)
- Weekly multiplier = stars 7d ÷ max(1, stars 30d ÷ 30 × 7)
- Fortnight multiplier = stars 14d ÷ max(1, stars 90d ÷ 90 × 14)
- Hot today = clamp(70 × log-scale(stars 1d, 1000) + 30 × breakout-scale(same-day, 4))
- Hot week = clamp(75 × log-scale(stars 7d, 5000) + 25 × breakout-scale(weekly, 3))
- Breakout = clamp(35 × breakout-scale(same-day, 4) + 40 × breakout-scale(weekly, 3) + 25 × breakout-scale(fortnight, 2.5))
| Date | Stars | Stars 1d | Stars 7d | Stars 14d | Stars 30d | Stars 90d | Same-day multiplier | Weekly multiplier | Fortnight multiplier | Hot today | Hot week | Breakout | Stored score |
|---|
Apache HttpComponents Client
Derived only from GitHub GraphQL starredAt events after daily star totals are reconciled.
42 observed daily rows. Missing days are not fabricated.
Per-day formula: 0.40 × Hot today + 0.40 × Hot week + 0.20 × Breakout.
- Same-day multiplier = stars 1d ÷ max(1, stars 7d ÷ 7)
- Weekly multiplier = stars 7d ÷ max(1, stars 30d ÷ 30 × 7)
- Fortnight multiplier = stars 14d ÷ max(1, stars 90d ÷ 90 × 14)
- Hot today = clamp(70 × log-scale(stars 1d, 1000) + 30 × breakout-scale(same-day, 4))
- Hot week = clamp(75 × log-scale(stars 7d, 5000) + 25 × breakout-scale(weekly, 3))
- Breakout = clamp(35 × breakout-scale(same-day, 4) + 40 × breakout-scale(weekly, 3) + 25 × breakout-scale(fortnight, 2.5))
| Date | Stars | Stars 1d | Stars 7d | Stars 14d | Stars 30d | Stars 90d | Same-day multiplier | Weekly multiplier | Fortnight multiplier | Hot today | Hot week | Breakout | Stored score |
|---|
Reliability score
Weekly average
Full metrics details
Derived from the displayed continuity, closure, shipping, liveness, and support-burden components.
Retrofit
Derived from the displayed continuity, closure, shipping, liveness, and support-burden components.
180 observed daily rows. Missing days are not fabricated.
Per-day formula: 0.30 × Continuity + 0.30 × Closure + 0.20 × Shipping + 0.10 × Liveness + 0.10 × Support burden.
- Continuity = 35% active ratio 90d + 20% active ratio 30d + 15% PR efficiency 90d + 10% PR efficiency 30d + 10% liveness + 10% observed-history coverage
- Closure = 55% PR merge efficiency 90d + 45% issue close efficiency 90d
- Shipping = 100 × (20% × release ratio 30d + 30% × release ratio 90d + 50% × release ratio 180d); ratios are releases ÷ 2, 6, and 12, capped at 1
- Support burden = 100 − 2 × open issues per 1,000 stars
- Liveness = 100 × exp(−pushed days ago ÷ 120)
Stars, issues, pull requests, and releases are daily observations. Pushed-days and license are repository snapshot-derived inputs and are not independent historical GitHub events.
| Date | Issues opened | Issues closed | PRs opened | PRs merged | Releases | Stars | Open issues | Pushed days ago | Continuity | Closure | Shipping | Liveness | Support burden | License | Observed days | Missing days | Needs healing | Stored score |
|---|
OkHttp
Derived from the displayed continuity, closure, shipping, liveness, and support-burden components.
180 observed daily rows. Missing days are not fabricated.
Per-day formula: 0.30 × Continuity + 0.30 × Closure + 0.20 × Shipping + 0.10 × Liveness + 0.10 × Support burden.
- Continuity = 35% active ratio 90d + 20% active ratio 30d + 15% PR efficiency 90d + 10% PR efficiency 30d + 10% liveness + 10% observed-history coverage
- Closure = 55% PR merge efficiency 90d + 45% issue close efficiency 90d
- Shipping = 100 × (20% × release ratio 30d + 30% × release ratio 90d + 50% × release ratio 180d); ratios are releases ÷ 2, 6, and 12, capped at 1
- Support burden = 100 − 2 × open issues per 1,000 stars
- Liveness = 100 × exp(−pushed days ago ÷ 120)
Stars, issues, pull requests, and releases are daily observations. Pushed-days and license are repository snapshot-derived inputs and are not independent historical GitHub events.
| Date | Issues opened | Issues closed | PRs opened | PRs merged | Releases | Stars | Open issues | Pushed days ago | Continuity | Closure | Shipping | Liveness | Support burden | License | Observed days | Missing days | Needs healing | Stored score |
|---|
Ktor
Derived from the displayed continuity, closure, shipping, liveness, and support-burden components.
41 observed daily rows. Missing days are not fabricated.
Per-day formula: 0.30 × Continuity + 0.30 × Closure + 0.20 × Shipping + 0.10 × Liveness + 0.10 × Support burden.
- Continuity = 35% active ratio 90d + 20% active ratio 30d + 15% PR efficiency 90d + 10% PR efficiency 30d + 10% liveness + 10% observed-history coverage
- Closure = 55% PR merge efficiency 90d + 45% issue close efficiency 90d
- Shipping = 100 × (20% × release ratio 30d + 30% × release ratio 90d + 50% × release ratio 180d); ratios are releases ÷ 2, 6, and 12, capped at 1
- Support burden = 100 − 2 × open issues per 1,000 stars
- Liveness = 100 × exp(−pushed days ago ÷ 120)
Stars, issues, pull requests, and releases are daily observations. Pushed-days and license are repository snapshot-derived inputs and are not independent historical GitHub events.
| Date | Issues opened | Issues closed | PRs opened | PRs merged | Releases | Stars | Open issues | Pushed days ago | Continuity | Closure | Shipping | Liveness | Support burden | License | Observed days | Missing days | Needs healing | Stored score |
|---|
Feign
Derived from the displayed continuity, closure, shipping, liveness, and support-burden components.
43 observed daily rows. Missing days are not fabricated.
Per-day formula: 0.30 × Continuity + 0.30 × Closure + 0.20 × Shipping + 0.10 × Liveness + 0.10 × Support burden.
- Continuity = 35% active ratio 90d + 20% active ratio 30d + 15% PR efficiency 90d + 10% PR efficiency 30d + 10% liveness + 10% observed-history coverage
- Closure = 55% PR merge efficiency 90d + 45% issue close efficiency 90d
- Shipping = 100 × (20% × release ratio 30d + 30% × release ratio 90d + 50% × release ratio 180d); ratios are releases ÷ 2, 6, and 12, capped at 1
- Support burden = 100 − 2 × open issues per 1,000 stars
- Liveness = 100 × exp(−pushed days ago ÷ 120)
Stars, issues, pull requests, and releases are daily observations. Pushed-days and license are repository snapshot-derived inputs and are not independent historical GitHub events.
| Date | Issues opened | Issues closed | PRs opened | PRs merged | Releases | Stars | Open issues | Pushed days ago | Continuity | Closure | Shipping | Liveness | Support burden | License | Observed days | Missing days | Needs healing | Stored score |
|---|
Apache HttpComponents Client
Derived from the displayed continuity, closure, shipping, liveness, and support-burden components.
42 observed daily rows. Missing days are not fabricated.
Per-day formula: 0.30 × Continuity + 0.30 × Closure + 0.20 × Shipping + 0.10 × Liveness + 0.10 × Support burden.
- Continuity = 35% active ratio 90d + 20% active ratio 30d + 15% PR efficiency 90d + 10% PR efficiency 30d + 10% liveness + 10% observed-history coverage
- Closure = 55% PR merge efficiency 90d + 45% issue close efficiency 90d
- Shipping = 100 × (20% × release ratio 30d + 30% × release ratio 90d + 50% × release ratio 180d); ratios are releases ÷ 2, 6, and 12, capped at 1
- Support burden = 100 − 2 × open issues per 1,000 stars
- Liveness = 100 × exp(−pushed days ago ÷ 120)
Stars, issues, pull requests, and releases are daily observations. Pushed-days and license are repository snapshot-derived inputs and are not independent historical GitHub events.
| Date | Issues opened | Issues closed | PRs opened | PRs merged | Releases | Stars | Open issues | Pushed days ago | Continuity | Closure | Shipping | Liveness | Support burden | License | Observed days | Missing days | Needs healing | Stored score |
|---|
If your team wants stricter transport control with less abstraction, OkHttp is closer to raw HTTP primitives. If you want a broader Kotlin-first application stack, Ktor can cover more than client calls. If you want declarative Java clients oriented around service contracts in microservice environments, Feign is a common path. Apache HttpComponents Client gives low-level, mature HTTP building blocks. Volley stays relevant for specific Android networking and caching patterns.
| Project | Repo | Adoption confidence (~6mo) | PRs merged (~6mo) | Star growth (~6mo) |
|---|---|---|---|---|
| Retrofit | https://github.com/square/retrofit | 68.50 | 279 | 896 |
| OkHttp | https://github.com/square/okhttp | metrics pending | 0 | metrics pending |
| Ktor | https://github.com/ktorio/ktor | metrics pending | 0 | metrics pending |
| Feign | https://github.com/OpenFeign/feign | metrics pending | 0 | metrics pending |
| Apache HttpComponents Client | https://github.com/apache/httpcomponents-client | metrics pending | 0 | metrics pending |
| Volley | https://github.com/google/volley | metrics pending | 0 | metrics pending |
OkHttp is the best overall alternative when you want maximum transport-level control and long-term ecosystem maturity while staying close to Retrofit-compatible patterns.
Conclusion
Retrofit is strongest when your team wants clean, type-safe HTTP contracts on Android or JVM without building a client framework from scratch. You gain a durable interface-first API layer, but you still need disciplined converter setup and integration tests for mapping correctness. Your most important operational takeaway is to treat Retrofit and OkHttp as one client system and standardize config, interceptors, and error handling centrally using the official repository, documentation, and community issue tracker.