REST APIs and JSON Handling

# CHAPTER 26

REST APIs and JSON Handling #

1. Chapter Introduction #

2. Learning Objectives #

• Understand what a REST API and JSON are.

• Understand the role of the Retrofit library.

• Create Data Classes to match JSON structure.

• Define an API Interface using @GET.

• Make an asynchronous network request.

3. Understanding JSON #

{
  "userId": 1,
  "id": 101,
  "title": "Learn Kotlin",
  "completed": false
}

4. Creating the Kotlin Data Class #

// The property names must match the JSON keys exactly!
data class Todo(
    val userId: Int,
    val id: Int,
    val title: String,
    val completed: Boolean
)

5. Defining the API Interface (Retrofit) #

*Crucial: Network requests are slow. We MUST mark them as suspend functions so they run in Coroutines!*

import retrofit2.http.GET

interface ApiService {
    
    // If the base URL is https://jsonplaceholder.typicode.com/
    // This calls https://jsonplaceholder.typicode.com/todos
    @GET("todos")
    suspend fun getTodos(): List<Todo> // Automatically returns a List of our Kotlin objects!
}

6. Setting Up Retrofit #

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

// Usually configured as a Singleton object
object RetrofitInstance {
    
    val api: ApiService by lazy {
        Retrofit.Builder()
            .baseUrl("https://jsonplaceholder.typicode.com/")
            .addConverterFactory(GsonConverterFactory.create()) // Use Gson to parse JSON
            .build()
            .create(ApiService::class.java)
    }
}

7. Making the Request #

import kotlinx.coroutines.*

fun main() = runBlocking {
    println("Fetching Todos from the Internet...")
    
    try {
        // This pauses the coroutine until the network request finishes
        val todos: List<Todo> = RetrofitInstance.api.getTodos()
        
        println("Successfully downloaded ${todos.size} items.")
        println("First Item: ${todos[0].title}")
        
    } catch (e: Exception) {
        println("Network Error: ${e.message}")
    }
}

8. Common Mistakes #

• Missing Internet Permission: In Android, if you do not add <uses-permission android:name="android.permission.INTERNET"/> to your AndroidManifest.xml, your app is strictly blocked from making network requests and will crash.

• Mismatched Variable Names: If the JSON key is firstname but your data class has val firstName, the parser will fail and return null. You must either match it exactly, or use annotations like @SerializedName("firstname") to bridge the gap.

9. Best Practices #

• Never hardcode API Keys: If you use a paid API, do not hardcode the key in your Kotlin file. Keep it in a secure local.properties file or inject it via build configurations.

10. Exercises #

1. 1. A server returns {"username": "dev123", "score": 95}. Write the Kotlin data class to hold this.

1. 2. Write a Retrofit Interface with a @GET("profile") method that returns this object.

11. MCQs with Answers #

12. Interview Questions #

• Q: Describe the architecture of a Retrofit setup. How do Data Classes, the API Interface, and Coroutines work together?

• Q: Why do we use try-catch blocks around network requests? Give two examples of exceptions that might occur. (Answer: No internet connection UnknownHostException, or Server Timeout SocketTimeoutException).

13. Summary #

14. Next Chapter Recommendation #