Retrofit

You are a Kotlin developer setting up Retrofit for API calls with coroutines support.

What to check first

• Verify build.gradle.kts includes Retrofit 2.9+ and OkHttp dependencies
• Confirm your target API level supports coroutines (API 21+)
• Check if kotlinx-coroutines-core is already in your dependencies

Steps

1. Add Retrofit, OkHttp, and coroutines dependencies to build.gradle.kts with versions 2.9.0+ for Retrofit
2. Create a data class matching your API response structure with @SerializedName annotations for JSON fields
3. Define an interface with suspend function declarations using @GET, @POST, @Path, and @Query annotations
4. Create a singleton object using the object keyword to instantiate Retrofit with OkHttpClient and GsonConverterFactory
5. Add interceptors to OkHttpClient.Builder() for logging, authentication headers, or request/response handling
6. Return the Retrofit service instance via a method that calls .create(YourApiInterface::class.java)
7. Launch coroutine calls from a ViewModel or repository using viewModelScope.launch or GlobalScope.launch (prefer viewModelScope)
8. Handle responses with try-catch blocks catching HttpException and IOException separately

Code

import retrofit2.Retrofit
import retrofit2.converter.gson.GsonConverterFactory
import retrofit2.http.*
import okhttp3.OkHttpClient
import okhttp3.logging.HttpLoggingInterceptor
import kotlinx.coroutines.launch
import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import com.google.gson.annotations.SerializedName

// Data class for API response
data class UserResponse(
    @SerializedName("id")
    val id: Int,
    @SerializedName("name")
    val name: String,
    @SerializedName("email")
    val email: String
)

// API interface with suspend functions
interface ApiService {
    @GET("users/{id}")
    suspend fun getUser(@Path("id") userId: Int): UserResponse

    @GET("users")
    suspend fun listUsers(@Query("limit") limit: Int = 10): List<UserResponse>

    @POST("users")
    suspend fun createUser(@Body user: UserResponse): UserResponse
}

// Retrofit singleton
object RetrofitClient {
    private const val BASE_URL = "https://jsonplaceholder.typicode.com/"

    private val httpClient = OkHttpClient.Builder()
        .addInterceptor(HttpLoggingInterceptor().apply {
            level = HttpLoggingInterceptor.Level.BODY
        })
        .addInterceptor { chain ->
            val request = chain.request().newBuilder()
                .addHeader("Authorization", "Bearer token

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change