Retrofit 3.0.0: Detailed Migration Guide

Blog Infos

Author

Vikas Soni

Published

8. December 2025

Topics

android, Android Development, Mobile, Networking, Retrofit

Author

Vikas Soni

Published

8. December 2025

Topics

android, Android Development, Mobile, Networking, Retrofit

Greetings, developers!
Retrofit is an extremely common idea in the Android space, regardless of whether you are an experienced Android developer or have just been interviewed for an Android role. Some developers have found the journey from AsyncTask, the first networking framework in Android, to Volley and ultimately Retrofit to be really fascinating. Fortunately, I was one of them.

I will only discuss Retrofit in this article, although it is a new AVATAR for projects that are entirely or partially constructed in Kotlin. Significant progress has been made since Retrofit was evaluated. Now that Retrofit 3.0.0 is fully created in Kotlin, a lot of potential has been released.
Even for entry-level developers, integrating Retrofit has been a breeze since the review of the most recent version, Retroft v3.0.0. Less boilerplate, improved null safety, better IDE type inference, and more understandable code are just a few of the advantages it offers over outdated systems.

Here, I’ll be sharing full migration guide for migration lagacy Retrofit implementation to latest version v3.0.0.

Tighten your seat-belt…😁

. Update dependencies to the latest Retrofit 3.0.0 and OkHttp 5.x artifacts.

	Before (2.x):

	implementation 'com.squareup.retrofit2:retrofit:2.9.0'
	implementation 'com.squareup.okhttp3:okhttp:3.14.9'


	After (3.0.0):

	implementation 'com.squareup.retrofit2:retrofit:3.0.0'
	implementation 'com.squareup.okhttp3:okhttp:5.0.0'

view raw build.gradle (app level) hosted with ❤ by GitHub

Refactor API interfaces to replace Call<T> return types with native suspend fun returning actual types.

	Before (2.x):

	@GET("users/{id}")
	fun getUser(@Path("id") id: String): Call<User>


	After (3.0.0):

	@GET("users/{id}")
	suspend fun getUser(@Path("id") id: String): User

view raw ApiService.kt hosted with ❤ by GitHub

. Remove all coroutine call adapter factories from your Retrofit client setup, as native coroutine support is built-in.

	Before (2.x):

	Retrofit.Builder().addCallAdapterFactory(CoroutineCallAdapterFactory())


	After (3.0.0):

	// No need for CoroutineCallAdapterFactory
	Retrofit.Builder()

view raw RetrofitSetup.kt hosted with ❤ by GitHub

Update converter factories using the simplified APIs with kotlinx.serialization, Moshi, or Gson as needed.

	Before (2.x):

	Retrofit.Builder().addConverterFactory(GsonConverterFactory.create())


	After (3.0.0):

	Retrofit.Builder().addConverterFactory(GsonConverterFactory.create())
	// Much the same, but can now use kotlinx.serialization more simply

view raw RetrofitSetup.kt hosted with ❤ by GitHub

Adjust exception handling: all suspend functions now throw exceptions directly; wrap network calls with try-catch for IOException (network) and HttpException (server).

	Before (2.x):

	call.enqueue(object : Callback<User> {
	override fun onFailure(call: Call<User>, t: Throwable) {
	// handle error
	}
	// ...
	})


	After (3.0.0):

	try {
	val user = apiService.getUser("123")
	} catch (e: IOException) {
	// handle network error
	} catch (e: HttpException) {
	// handle HTTP error
	}

view raw UserViewModel.kt hosted with ❤ by GitHub

Remove RxJava call adapters if not in direct use, or add new external dependencies for RxJava support if required.

	Before (2.x):

	Retrofit.Builder()
	.addCallAdapterFactory(RxJava2CallAdapterFactory.create())


	After (3.0.0):
	// Remove adapter unless still needed
	// If needed, add the new external RxJava adapter library dependency and use accordingly

view raw RetrofitSetup.kt hosted with ❤ by GitHub

Move away from using Response<T> wrappers unless explicitly needed for advanced error modeling.

	Before (2.x):

	@GET("users/{id}")
	fun getUser(@Path("id") id: String): Call<Response<User>>


	After (3.0.0):

	@GET("users/{id}")
	suspend fun getUser(@Path("id") id: String): User
	// Use Response<User> only if explicit HTTP info needed

view raw ApiService.kt hosted with ❤ by GitHub

Test your application thoroughly with coroutine-based fake API services, ensuring clean error and null safety handling.

	Typical Testing (3.0.0):

	@Test
	fun testGetUser() = runBlocking {
	val fakeApi = FakeApiService()
	val user = fakeApi.getUser("123")
	// assertions...
	}

view raw UserViewModelTest.kt hosted with ❤ by GitHub

Ensure your codebase targets Java 8+ (or Android API 21+) and remove legacy compatibility workarounds.

	Before (2.x):

	android {
	compileOptions { sourceCompatibility JavaVersion.VERSION_1_7 }
	}


	After (3.0.0):

	android {
	compileOptions { sourceCompatibility JavaVersion.VERSION_1_8 }
	defaultConfig { minSdk = 21 }
	}