Working with APIs and JSON (Retrofit)

# CHAPTER 20

Working with APIs and JSON (Retrofit) #

1. Introduction #

2. Learning Objectives #

• Understand the structure of a REST API and JSON payload.

• Configure internet permissions within the Android Manifest.

• Integrate the Retrofit and Gson/Moshi libraries via Gradle.

• Define a Retrofit HTTP Interface (GET, POST).

• Execute network calls securely utilizing Coroutines and viewModelScope.

3. Understanding JSON #

{
  "id": 1,
  "name": "Leanne Graham",
  "email": "Sincere@april.biz"
}

Our goal is to automatically convert that JSON text into a Kotlin Data Class:

data class User(val id: Int, val name: String, val email: String)

4. Step 1: Internet Permissions and Gradle #

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

Next, add Retrofit and Gson (the JSON parser) to your build.gradle.kts (Module :app) dependencies:

implementation("com.squareup.retrofit2:retrofit:2.9.0")
implementation("com.squareup.retrofit2:converter-gson:2.9.0")

*Click "Sync Now" in the top right corner!*

5. Step 2: The Data Class and The API Interface #

1. Create the Data Class: The variable names MUST perfectly match the keys in the JSON payload!

data class User(
    val id: Int,
    val name: String,
    val email: String
)

2. Create the API Interface: Retrofit generates the complex networking code for us. We just need to define an Interface that outlines the "Endpoints" we want to hit. Notice we use the suspend keyword because networking takes time!

import retrofit2.http.GET

interface ApiService {
    
    // The @GET annotation defines the endpoint URL!
    // It will append "/users" to the base URL we define later.
    @GET("/users")
    suspend fun getUsers(): List<User> // Automatically parses the JSON into a List of User objects!
}

6. Step 3: Building the Retrofit Instance #

import retrofit2.Retrofit
import retrofit2.converter.gson.GsonConverterFactory

object RetrofitClient {

    private const val BASE_URL = "https://jsonplaceholder.typicode.com"

    // The 'by lazy' block ensures this is only built ONCE when first accessed
    val apiService: ApiService by lazy {
        val retrofit = Retrofit.Builder()
            .baseUrl(BASE_URL)
            .addConverterFactory(GsonConverterFactory.create()) // Tells it to use Gson for JSON!
            .build()

        retrofit.create(ApiService::class.java)
    }
}

7. Step 4: Executing the Call in the ViewModel #

import androidx.lifecycle.LiveData
import androidx.lifecycle.MutableLiveData
import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch

class UserViewModel : ViewModel() {

    private val _users = MutableLiveData<List<User>>()
    val users: LiveData<List<User>> get() = _users

    // For error handling
    private val _error = MutableLiveData<String>()
    val error: LiveData<String> get() = _error

    fun fetchUsersFromNetwork() {
        // Launch on IO thread because networking is heavy!
        viewModelScope.launch(Dispatchers.IO) {
            try {
                // This ONE line does the HTTP request, waits for the response, and parses the JSON!
                val userList = RetrofitClient.apiService.getUsers()
                
                // Switch to Main thread to update LiveData!
                _users.postValue(userList) // .postValue() is a shortcut for updating LiveData from a background thread!
                
            } catch (e: Exception) {
                // Catch timeouts, missing internet, or 404 errors!
                _error.postValue("Network Error: ${e.message}")
            }
        }
    }
}

*Your Activity can now observe the users LiveData and instantly display the downloaded data in a RecyclerView!*

8. @SerializedName (Fixing JSON Mismatches) #

import com.google.gson.annotations.SerializedName

data class User(
    val id: Int,
    @SerializedName("first_name_str") // The ugly JSON key
    val firstName: String             // The beautiful Kotlin variable
)

9. Common Mistakes #

• Forgetting the Manifest Permission: If you write perfect Retrofit code, but forget to add <uses-permission android:name="android.permission.INTERNET" /> to the Manifest, the app will instantly crash with a SecurityException: Permission denied (missing INTERNET permission?).

• Trailing Slashes in URLs: Retrofit is very strict about URLs. If your Base URL ends with a slash (https://api.com/) and your endpoint also starts with a slash (@GET("/users")), Retrofit will crash because it combines them into https://api.com//users. Standardize your slash placement.

10. Best Practices #

• Dependency Injection: Building RetrofitClient as an object (Singleton) is great for beginners. However, in enterprise applications, networking clients are injected using tools like Hilt or Dagger to allow for robust unit testing and mocking.

11. Exercises #

1. 1. Ensure your device/emulator has internet access. Add the Internet permission to your AndroidManifest.xml.

1. 2. Review the public API at https://jsonplaceholder.typicode.com/posts. Create a Kotlin Data Class named Post that mirrors the JSON structure (userId, id, title, body).

12. Coding Challenges #

13. MCQ Quiz with Answers #

14. Interview Questions #

• Q: Explain the architectural role of GsonConverterFactory within the Retrofit initialization pipeline. How does it eliminate boilerplate XML/JSON parsing logic?

• Q: Detail the structural advantage of declaring Retrofit endpoints as suspend functions. How does this integrate seamlessly with the MVVM viewModelScope architecture?

• Q: Contrast LiveData.value with LiveData.postValue(). Why must a developer strictly utilize .postValue() when updating state directly from an asynchronous Retrofit IO thread?

15. FAQs #

16. Summary #

17. Next Chapter Recommendation #