Retrofit in Android: Complete Guide

plugins { id("org.jetbrains.kotlin.plugin.serialization") }
dependencies {
    implementation("com.squareup.retrofit2:retrofit:<version>")
    implementation("com.squareup.retrofit2:converter-kotlinx-serialization:<version>")
    implementation("com.squareup.okhttp3:okhttp:<version>")
    implementation("com.squareup.okhttp3:logging-interceptor:<version>")
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:<version>")
}

<uses-permission android:name="android.permission.INTERNET" />

@Serializable
data class UserDto(
    val id: String,
    val name: String,
    @SerialName("avatar_url") val avatarUrl: String? = null,   // map snake_case, tolerate missing
)

@Serializable
data class CreatePostRequest(val title: String, val body: String, val tags: List<String> = emptyList())

@Serializable
data class PostDto(val id: Long, val title: String, val body: String)

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

    @GET("posts")
    suspend fun getPosts(
        @Query("page") page: Int,
        @Query("limit") limit: Int = 20,
        @Query("tag") tag: String? = null,          // null query params are omitted
    ): List<PostDto>

    @POST("posts")
    suspend fun createPost(@Body request: CreatePostRequest): PostDto

    @DELETE("posts/{id}")
    suspend fun deletePost(@Path("id") id: Long): Response<Unit>   // Response<T> when you need status/headers

    @Multipart
    @POST("uploads")
    suspend fun upload(@Part file: MultipartBody.Part): UploadResult
}

object Network {
    private val json = Json {
        ignoreUnknownKeys = true      // new server fields won't crash old app versions
        explicitNulls = false
    }

    private val okHttp = OkHttpClient.Builder()
        .connectTimeout(15, TimeUnit.SECONDS)
        .readTimeout(30, TimeUnit.SECONDS)
        .addInterceptor(HttpLoggingInterceptor().apply {
            level = if (BuildConfig.DEBUG) HttpLoggingInterceptor.Level.BODY else HttpLoggingInterceptor.Level.NONE
        })
        .build()

    val blogApi: BlogApi = Retrofit.Builder()
        .baseUrl("https://api.example.com/v1/")     // must end with "/"
        .client(okHttp)
        .addConverterFactory(json.asConverterFactory("application/json".toMediaType()))
        .build()
        .create(BlogApi::class.java)
}

class PostRepository(private val api: BlogApi) {
    suspend fun latestPosts(page: Int): List<Post> = api.getPosts(page).map { it.toDomain() }
}

class BlogApiTest {
    private val server = MockWebServer()
    private lateinit var api: BlogApi

    @Before fun setUp() {
        server.start()
        api = Retrofit.Builder()
            .baseUrl(server.url("/"))
            .addConverterFactory(Json { ignoreUnknownKeys = true }.asConverterFactory("application/json".toMediaType()))
            .build().create(BlogApi::class.java)
    }
    @After fun tearDown() = server.shutdown()

    @Test fun `parses user and ignores unknown fields`() = runTest {
        server.enqueue(MockResponse().setBody("""{"id":"7","name":"Asha","extra":true}"""))
        val user = api.getUser("7")
        assertEquals("Asha", user.name)
        assertEquals("/users/7", server.takeRequest().path)
    }
}