Welcome to the second lesson in our journey of interacting with APIs in Kotlin. Previously, we laid a strong foundation by understanding RESTful APIs and using manual tools to craft and send a GET request to an endpoint. Now, we are transitioning to automate this process using libraries, specifically OkHttp. While Kotlin's standard library provides basic HTTP functionalities, OkHttp excels with its user-friendly API and robust capabilities for handling HTTP requests more efficiently and smoothly. This makes it an invaluable tool in web development and API integration, providing features like connection pooling, transparent GZIP, and response caching, which go beyond the basic functionalities offered by the native options.

To make HTTP requests in Kotlin, we will use the OkHttp library, a user-friendly and powerful library for handling HTTP requests. If you are working within an IDE like IntelliJ IDEA, you can integrate OkHttp by adding the following line to your build.gradle file in the dependencies section if you're using Gradle:

Kotlin
Copy to clipboard
1dependencies {
2    implementation("com.squareup.okhttp3:okhttp:4.9.3")
3    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.3.2")
4}

After adding the dependencies, make sure to sync your project to include the necessary libraries.

Setting up JSON serialization is crucial for parsing responses because it allows us to convert JSON data from the API into Kotlin objects that we can easily manipulate in our code. This offers a seamless integration between the data formats used by web services and the Kotlin programming language, significantly simplifying the process of handling JSON data.

To do this you need to add the kotlinx serialization library:

Kotlin
Copy to clipboard
1dependencies {
2    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.3.2")
3}

And don't forget to apply the plugin:

Kotlin
Copy to clipboard
1plugins {
2    kotlin("plugin.serialization") version "1.5.30"
3}

When interacting with an API, it's helpful to define a base URL for the service you're communicating with. This makes your code more modular and easy to maintain, allowing you to change the root of your API URL in one place without modifying each request.

Kotlin
Copy to clipboard
1// Base URL for the API
2val baseUrl = "http://localhost:8000"

By setting this base URL, we can easily concatenate endpoints for different services within the API, making our code cleaner and more adaptable.

APIs often run on specific ports to separate different services or applications on the same server. In local development, localhost typically refers to 127.0.0.1, the local loopback address, but the API server must still be listening on the specified port. The default HTTP port is 80, and HTTPS is 443, but many development APIs use custom ports (e.g., 8000 in this case). Ensure that the API server is running on the correct port before making requests, as an incorrect port leads to connection failures.

Let's dive into the process of fetching data from an API using Kotlin's OkHttp library. Our goal is to retrieve a list of to-do items from the /todos endpoint using the GET method.

Kotlin
Copy to clipboard
1import okhttp3.OkHttpClient
2import okhttp3.Request
3import kotlinx.serialization.*
4import kotlinx.serialization.json.*
5
6// Define a data class to represent a to-do item; each property corresponds to a JSON field
7@Serializable
8data class Todo(
9    val description: String,
10    val done: Boolean,
11    val id: Int,
12    val title: String
13)
14
15fun fetchTodos() {
16    // Initialize the OkHttpClient which will be used to send requests
17    val client = OkHttpClient()
18
19    // Build a GET request to the /todos endpoint, appended to the base URL
20    val request = Request.Builder()
21        .url("$baseUrl/todos")
22        .build()
23
24    // Execute the request and handle the response
25    client.newCall(request).execute().use { response ->
26        // Print the raw response body received from the server
27        println("Raw Response:")
28        println(response.body?.string())
29    }
30}
31
32fetchTodos()

By using OkHttp's newCall().execute() method, we send a GET request to the constructed full URL. The response from the server is then printed.

To determine the outcome of an HTTP request, we use the response.code method to check the status code returned by the server. When the server responds with a status code of 200, it signifies a successful interaction. In such cases, we can confidently parse the body in JSON format using kotlinx.serialization.

Kotlin
Copy to clipboard
1client.newCall(request).execute().use { response ->
2    // Check if the server response status code is 200 (OK)
3    if (response.code == 200) {
4        println("Todos retrieved successfully:")
5
6        // Get the response body as a string
7        val json = response.body?.string() ?: ""
8
9        // Deserialize the JSON string into a list of Todo objects using kotlinx.serialization
10        val todos = Json.decodeFromString<List<Todo>>(json)
11
12        // Iterate through the list of Todo objects and print each one
13        todos.forEach { todo ->
14            println("Title: ${todo.title}, Description: ${todo.description}, Done: ${todo.done}")
15        }
16    }
17}

Errors can occur on both the client and server sides. A 400 status code indicates a mistake in the request, often due to incorrect syntax from the client side. To understand these errors better, you can print the response body, which provides more details about what went wrong.

Kotlin
Copy to clipboard
1// Check if the server response status code is 400 (Bad Request)
2if (response.code == 400) {
3    println("\nBad Request. The server could not understand the request due to invalid syntax.")
4
5    // Retrieve the response body which contains error details
6    val error = response.body?.string()
7
8    // Print the error details for further analysis
9    println("Error Details: $error")
10}

A 401 status code indicates an unauthorized request, often due to missing or invalid credentials. This situation requires the user to address authentication issues to proceed.

Kotlin
Copy to clipboard
1// Check if the server response status code is 401 (Unauthorized)
2if (response.code == 401) {
3    println("\nUnauthorized. Access is denied due to invalid credentials.")
4
5    // Retrieve the response body which contains error details
6    val error = response.body?.string()
7
8    // Print the error details to understand the authentication issue
9    println("Error Details: $error")
10}

When encountering a 404 status code, it means the requested resource is not found, often pointing to a missing resource or incorrect endpoint.

Kotlin
Copy to clipboard
1// Check if the server response status code is 404 (Not Found)
2if (response.code == 404) {
3    println("\nNot Found. The requested resource could not be found on the server.")
4
5    // Retrieve the response body which contains error details
6    val error = response.body?.string()
7
8    // Print the error details to determine what might be missing or incorrect
9    println("Error Details: $error")
10}

A 500 status code reflects an internal server error, indicating the server encountered an unexpected situation. Such cases usually require investigation on the server side to resolve the issue.

Kotlin
Copy to clipboard
1// Check if the server response status code is 500 (Internal Server Error)
2if (response.code == 500) {
3    println("\nInternal Server Error. The server has encountered a situation it doesn't know how to handle.")
4
5    // Retrieve the response body which contains error details
6    val error = response.body?.string()
7
8    // Print the error details to understand the server-side issue
9    println("Error Details: $error")
10}

For responses falling outside the common codes, a generic approach captures these cases, ensuring all responses are analyzed for potential issues.

Kotlin
Copy to clipboard
1// Handle any unexpected status codes that do not fall into predefined categories
2else {
3    println("\nUnexpected Status Code: ${response.code}")
4
5    // Retrieve the response body which may contain additional information
6    val error = response.body?.string()
7
8    // Print the error details to help diagnose unexpected responses
9    println("Error Details: $error")
10}

By handling these diverse status codes, we ensure robust API interactions and a better understanding of the server's communication.

In this lesson, we've explored the powerful capability of Kotlin's OkHttp library to make GET requests to an API. We've seen how to retrieve and handle responses effectively, interpreting HTTP status codes to understand the server's communication. This knowledge is crucial for creating reliable interactions with APIs. As you move on to the practice exercises, focus on experimenting with the code snippets and handling various status codes to solidify your understanding. In future lessons, we will build on this foundation, unlocking the potential to perform more complex tasks like updating and manipulating API data. Keep up the great work as you advance through the course!