API interface definition in Android Kotlin - Mini App: Build & Ship

Build: API Interface Definition Screen

This screen shows how to define a simple API interface in Kotlin for Android using Retrofit. It defines endpoints to fetch a list of items and a single item by ID.

Target UI

-------------------------
| API Interface Example  |
|-----------------------|
| GET /items            |
| GET /items/{id}       |
|-----------------------|
| Define interface with |
| Retrofit annotations  |
-------------------------

Create a Kotlin interface named ApiService

Define a function to get a list of items with @GET("items")

Define a function to get a single item by ID with @GET("items/{id}") and @Path parameter

Use Retrofit Call<T> as return type for both functions

Starter Code

Android Kotlin

package com.example.api

import retrofit2.Call
import retrofit2.http.GET
import retrofit2.http.Path

// TODO: Define ApiService interface here

Task 1

Task 2

Task 3

Solution

Android Kotlin

package com.example.api

import retrofit2.Call
import retrofit2.http.GET
import retrofit2.http.Path

interface ApiService {
  @GET("items")
  fun getItems(): Call<List<Item>>

  @GET("items/{id}")
  fun getItemById(@Path("id") id: Int): Call<Item>
}

// Data class for Item
data class Item(val id: Int, val name: String)

We define an interface ApiService with Retrofit annotations to specify HTTP methods and endpoints.

The @GET("items") annotation marks getItems() as a GET request to the "items" endpoint, returning a list of Item.

The @GET("items/{id}") annotation marks getItemById() as a GET request to "items/{id}" where {id} is a path parameter injected by @Path("id").

Both functions return Call objects from Retrofit, which can be used to enqueue network requests asynchronously.

Final Result

Completed Screen

-------------------------
| API Interface Example  |
|-----------------------|
| GET /items            |
| GET /items/{id}       |
|-----------------------|
| interface ApiService { |
|   fun getItems()      |
|   fun getItemById(id) |
| }                     |
-------------------------

No user interaction - this is a code definition screen

Used by Retrofit to make network calls in the app

Stretch Goal

Add a POST method to create a new item with @Body parameter

💡 Hint

Use @POST("items") and a function like createItem(@Body item: Item): Call<Item>

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