Why API interface definition in Android Kotlin? - Purpose & Use Cases

The Big Idea

What if you could write your app's online requests just once and never worry about messy code again?

The Scenario

Imagine you want your app to get weather data from a website. Without a clear plan, you write different code everywhere to ask for data, handle responses, and convert them into something your app can use.

The Problem

This manual way is slow and confusing. You might write the same code many times, make mistakes in how you ask for data, or forget to handle errors. It becomes hard to fix or change later.

The Solution

API interface definition lets you create a simple blueprint for how your app talks to the website. You write this blueprint once, and your app knows exactly how to ask for data and what to expect back. This saves time and avoids mistakes.

Before vs After

✗ Before

val response = httpClient.get("https://api.weather.com/data")
val json = parseJson(response)
val temp = json["temperature"]

✓ After

interface WeatherApi {
  @GET("data")
  suspend fun getWeather(): WeatherResponse
}

What It Enables

It makes your app's communication with online services clear, reusable, and easy to update.

Real Life Example

When you open a shopping app, it uses API interface definitions to quickly get product lists, prices, and images from the store's server without confusion or delay.

Key Takeaways

Manual network calls are repetitive and error-prone.

API interface definitions create a clear contract for data exchange.

This approach saves time and makes apps easier to maintain.

Practice

1. What is the main purpose of defining an API interface in Android Kotlin using Retrofit?

easy

A. To store data locally on the device

B. To specify how the app communicates with web services

C. To create UI components for the app

D. To manage app navigation between screens

Solution

1. Step 1: Understand API interface role

   An API interface defines methods that describe how the app sends requests and receives responses from web services.

2. Step 2: Identify the correct purpose

   It is not related to UI, local storage, or navigation but specifically to communication with web services.

3. Final Answer:

   To specify how the app communicates with web services -> Option B

4. Quick Check:

   API interface = communication with web services [OK]

Hint: API interfaces define web communication methods [OK]

Common Mistakes:

• Confusing API interface with UI components
• Thinking API interfaces handle local data storage
• Assuming API interfaces manage app navigation

2. Which of the following is the correct way to define a GET request method in a Retrofit API interface?

easy

A. @GET("users") fun getUser(): Call<User>

B. @GET fun getUser(): User

C. fun getUser(): Call<User>

D. fun getUser() @GET("users"): Call<User>

Solution

1. Step 1: Recall Retrofit syntax for GET

   Retrofit uses @GET annotation with the endpoint path as a string parameter before the method declaration.

2. Step 2: Check method return type and annotation placement

   The method should return Call<User> and the annotation must be above the method signature.

3. Final Answer:

   @GET("users") fun getUser(): Call<User> -> Option A

4. Quick Check:

   @GET("endpoint") before method with Call return [OK]

Hint: Annotations go above method with endpoint string [OK]

Common Mistakes:

• Placing @GET after method name
• Omitting endpoint path in @GET
• Returning User directly instead of Call<User>

3. Given this Retrofit interface method:

@POST("login")
fun loginUser(@Body user: User): Call<Response>

What happens when loginUser is called?

medium

A. Throws a compile-time error due to missing annotation

B. Sends a GET request to 'login' without any data

C. Sends a POST request to 'login' with user data in the body

D. Returns user data without network call

Solution

1. Step 1: Analyze the method annotation and parameters

   The method uses @POST("login") which means it sends a POST request to the 'login' endpoint.

2. Step 2: Understand the @Body parameter

   The @Body annotation sends the 'user' object as the request body in the POST request.

3. Final Answer:

   Sends a POST request to 'login' with user data in the body -> Option C

4. Quick Check:

   @POST with @Body sends data in POST request [OK]

Hint: @POST with @Body sends data in request body [OK]

Common Mistakes:

• Confusing POST with GET request
• Ignoring the @Body annotation
• Assuming no network call happens

4. Identify the error in this Retrofit API interface method:

@GET("users/{id}")
fun getUser(@Path userId: Int): Call<User>

medium

A. The return type Call<User> is incorrect

B. The method is missing the @Body annotation

C. The method should use @POST instead of @GET

D. The @Path parameter name does not match the placeholder in the URL

Solution

1. Step 1: Check the URL placeholder and @Path parameter

   The URL has {id} but the parameter is named userId, so they do not match.

2. Step 2: Understand Retrofit @Path usage

   The name inside @Path must match the placeholder in the URL exactly to replace it correctly.

3. Final Answer:

   The @Path parameter name does not match the placeholder in the URL -> Option D

4. Quick Check:

   @Path name must match URL placeholder [OK]

Hint: Match @Path name exactly with URL placeholder [OK]

Common Mistakes:

• Using different names for @Path and URL placeholder
• Confusing @GET with @POST
• Adding unnecessary @Body in GET request

5. You want to define an API interface method that sends a POST request to "submit" with a JSON body and expects a Map response. Which is the correct method signature?

hard

A. @POST("submit") fun submitData(@Body data: Map): Call>

B. fun submitData(@Body data: Map): Map

C. @POST fun submitData(data: Map): Call>

D. @POST("submit") fun submitData(@Body data: Map): Map

Solution

1. Step 1: Confirm the annotation and endpoint

   The method must have @POST("submit") to specify the POST request and endpoint.

2. Step 2: Check parameter and return types

   The parameter should be annotated with @Body to send JSON data, and the return type should be Call> for Retrofit's asynchronous call.

3. Final Answer:

   @POST("submit") fun submitData(@Body data: Map): Call> -> Option A

4. Quick Check:

   @POST with @Body and Call return type [OK]

Hint: Use @POST with @Body and Call<> return type [OK]

Common Mistakes:

• Omitting endpoint path in @POST
• Returning Map directly instead of Call<Map>
• Missing @Body annotation on parameter