Integrating a Public REST API into an Android Application

Course: Android App Development

Topic: Integrating a Public REST API into an Android Application

Course Link: Android App Development Course

Demo Link: Register for a Course Demo

Website: JustAcademy

1. Introduction

Modern Android applications often need information that is stored on remote servers. Examples include weather applications retrieving forecasts, shopping applications loading products, news applications displaying articles, and educational applications retrieving course details.

A REST API (Representational State Transfer Application Programming Interface) allows an Android application to communicate with a remote service over HTTP or HTTPS. The application sends a request to a specific endpoint, and the server returns a response containing data or an error.

A public REST API is an API that developers can access without necessarily having a private account or invitation. Some public APIs are completely open, while others require an API key, impose request limits, or require registration. Always read the API's documentation and usage policy before integrating it into an application.

In Android development, libraries such as Retrofit simplify HTTP requests, while Kotlin Serialization or Gson can convert JSON responses into Kotlin objects. Android's official networking guidance also recommends using appropriate network permissions and secure HTTPS communication. Android Developers: Connect to the Network.

2. Learning Objectives

• Understand REST APIs, endpoints, resources, and HTTP methods.
• Learn how Android communicates with a remote API.
• Configure Internet permission in the Android manifest.
• Integrate Retrofit into an Android project.
• Create Kotlin data models for API responses.
• Parse JSON responses using Kotlin Serialization.
• Implement GET and POST requests.
• Handle loading states, network failures, and HTTP errors.
• Display API data in a Jetpack Compose interface.
• Apply security, performance, and testing best practices.

3. What Is a REST API?

A REST API is a web interface that exposes resources through URLs and uses standard HTTP methods to perform operations. A resource might represent a user, product, article, order, or course.

For example, a product API might provide the following endpoints:

The exact endpoints and supported methods depend on the API. An endpoint shown in an example is not guaranteed to exist on every service.

4. How Android Communicates with an API

When a user opens a screen that needs remote information, the application usually follows this sequence:

1. The user opens a screen or performs an action.
2. The ViewModel requests data from a repository.
3. The repository calls the API service.
4. Retrofit constructs and sends an HTTP request using the configured HTTP client.
5. The server processes the request and returns an HTTP response.
6. The configured converter parses the response body into a Kotlin object.
7. The repository returns the result to the ViewModel.
8. The ViewModel updates the UI state.
9. The UI displays the data, a loading indicator, or an error message.

User
 |
 v
Android UI (Compose)
 |
 v
ViewModel
 |
 v
Repository
 |
 v
Retrofit API Interface
 |
 v
HTTP Client
 |
 v
Public REST API
 |
 v
JSON Response
 |
 v
Kotlin Model
 |
 v
UI State and Screen

This separation makes applications easier to test and maintain because the UI does not need to manage HTTP requests or JSON parsing directly.

5. Selecting a Public API

Before writing code, select an API that provides the information required by your application. For practice, you can use a test API such as JSONPlaceholder, which provides sample resources for learning and demonstrations.

Example API: JSONPlaceholder

For this lesson, we will retrieve posts from the following endpoint:

https://jsonplaceholder.typicode.com/posts

A sample response looks like this:

[
  {
    "userId": 1,
    "id": 1,
    "title": "Sample post title",
    "body": "This is an example post body."
  },
  {
    "userId": 1,
    "id": 2,
    "title": "Another post title",
    "body": "This is another example post body."
  }
]

The values above illustrate the response structure. Actual response content can differ. JSONPlaceholder is a demonstration service; do not treat it as a production database for your application.

6. Configure the Android Project

6.1 Create an Android Studio Project

1. Open Android Studio.
2. Create a new project using an Empty Activity template.
3. Select Kotlin as the programming language.
4. Choose a suitable minimum SDK for your application.
5. Allow Gradle to finish syncing before adding the networking code.

6.2 Add Internet Permission

Open AndroidManifest.xml and add the Internet permission outside the application element but inside the manifest element.

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.INTERNET" />

    <application
        android:allowBackup="true"
        android:label="Public API Demo"
        android:supportsRtl="true"
        android:theme="@style/Theme.YourApp">
        <activity
            android:name=".MainActivity"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

Preserve the application settings and theme already generated by Android Studio; the example is illustrative. The INTERNET permission is a normal permission and does not require a runtime permission dialog. If your app needs to check network connectivity, you may also declare ACCESS_NETWORK_STATE, but it is not required simply to send HTTP requests.

6.3 Add Networking Dependencies

Retrofit helps define typed HTTP endpoints, and Kotlin Serialization provides JSON serialization and deserialization. Add compatible versions to your app module's build.gradle.kts.

plugins {
    // Keep this version aligned with the Kotlin version used by the project.
    id("org.jetbrains.kotlin.plugin.serialization") version "YOUR_KOTLIN_VERSION"
}

dependencies {
    implementation("com.squareup.retrofit2:retrofit:YOUR_RETROFIT_VERSION")
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:YOUR_SERIALIZATION_VERSION")
    implementation("com.squareup.retrofit2:converter-kotlinx-serialization:YOUR_RETROFIT_VERSION")
}

Replace each placeholder with a compatible published version. If your project uses a Gradle version catalog or a convention plugin, configure the plugin and dependencies there instead of duplicating plugin declarations. Follow the Retrofit documentation for the converter compatible with your selected Retrofit release: Retrofit Documentation.

7. Create a Kotlin Data Model

The data model describes the JSON structure that the application expects. For the posts endpoint, define a Kotlin data class with properties corresponding to the JSON fields.

import kotlinx.serialization.Serializable

@Serializable
data class Post(
    val userId: Int,
    val id: Int,
    val title: String,
    val body: String
)

The @Serializable annotation enables Kotlin Serialization to generate a serializer for this class when the serialization plugin is configured correctly.

Important model design considerations:

• Use appropriate Kotlin types for the JSON values.
• Represent nullable fields with nullable types, such as String?.
• Use default values only when missing fields have a valid meaning.
• Use @SerialName when a JSON key differs from the Kotlin property name.
• Check whether the API returns a raw list or an object containing a list.

8. Define the REST API Interface

Retrofit allows you to describe API endpoints using Kotlin interfaces and annotations. It then generates the implementation that performs the HTTP request.

import retrofit2.http.GET
import retrofit2.http.Path
import retrofit2.http.Query

interface PostApi {
    @GET("posts")
    suspend fun getPosts(): List<Post>

    @GET("posts/{id}")
    suspend fun getPostById(
        @Path("id") id: Int
    ): Post

    @GET("posts")
    suspend fun getPostsByUser(
        @Query("userId") userId: Int
    ): List<Post>
}

Understanding the annotations:

Functions marked suspend can be called from Kotlin coroutines. This is a convenient way to make asynchronous requests without blocking the main thread.

9. Configure Retrofit

Create a Retrofit instance with the base URL and the Kotlin Serialization converter. The base URL must be valid and should end with a slash for predictable relative endpoint resolution.

import kotlinx.serialization.json.Json
import okhttp3.MediaType.Companion.toMediaType
import retrofit2.Retrofit
import retrofit2.converter.kotlinx.serialization.asConverterFactory

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

    private val json = Json {
        ignoreUnknownKeys = true
    }

    private val contentType =
        "application/json".toMediaType()

    private val retrofit: Retrofit =
        Retrofit.Builder()
            .baseUrl(BASE_URL)
            .addConverterFactory(
                json.asConverterFactory(contentType)
            )
            .build()

    val postApi: PostApi =
        retrofit.create(PostApi::class.java)
}

The configured JSON instance ignores extra fields that are not represented in the data model. This is useful when the API adds fields that the app does not need. Required fields and data types still need to match the response.

The Kotlin Serialization converter package and setup should match the Retrofit version used by the project. If your dependency version exposes a different converter setup, follow its official documentation rather than mixing incompatible examples.

10. Create a Repository

A repository separates the data-access logic from the UI. It provides a single place to retrieve data and can later be extended with caching, local databases, or alternative data sources.

class PostRepository(
    private val api: PostApi
) {
    suspend fun getPosts(): List<Post> {
        return api.getPosts()
    }

    suspend fun getPostById(id: Int): Post {
        return api.getPostById(id)
    }

    suspend fun getPostsByUser(
        userId: Int
    ): List<Post> {
        return api.getPostsByUser(userId)
    }
}

The repository does not need to manually parse the response because Retrofit's converter converts the JSON body into the declared Kotlin return type.

11. Handle Loading, Success, and Error States

A network request may take time or fail. A reliable application should communicate its current state instead of leaving the screen blank or crashing.

11.1 Define UI State

sealed interface PostsUiState {
    data object Loading : PostsUiState
    data class Success(
        val posts: List<Post>
    ) : PostsUiState
    data class Error(
        val message: String
    ) : PostsUiState
}

11.2 Create a ViewModel

import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.launch
import retrofit2.HttpException
import java.io.IOException

class PostsViewModel(
    private val repository: PostRepository
) : ViewModel() {

    private val _uiState =
        MutableStateFlow<PostsUiState>(
            PostsUiState.Loading
        )

    val uiState: StateFlow<PostsUiState> =
        _uiState.asStateFlow()

    fun loadPosts() {
        viewModelScope.launch {
            _uiState.value = PostsUiState.Loading

            try {
                val posts = repository.getPosts()
                _uiState.value =
                    PostsUiState.Success(posts)
            } catch (e: CancellationException) {
                throw e
            } catch (e: IOException) {
                _uiState.value =
                    PostsUiState.Error(
                        "Network connection failed. Please try again."
                    )
            } catch (e: HttpException) {
                _uiState.value =
                    PostsUiState.Error(
                        "The server returned HTTP ${e.code()}."
                    )
            } catch (e: Exception) {
                _uiState.value =
                    PostsUiState.Error(
                        "Unable to load posts. Please try again."
                    )
            }
        }
    }
}

This example rethrows coroutine cancellation rather than treating it as a normal application failure. In production, consider a dedicated error model, structured logging, retry policies, and dependency injection for creating the repository and ViewModel.

12. Display API Data Using Jetpack Compose

After the ViewModel exposes its state, Jetpack Compose can display the result. The following screen uses a LazyColumn to display posts efficiently.

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.material3.Button
import androidx.compose.material3.CircularProgressIndicator
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp

@Composable
fun PostsScreen(
    viewModel: PostsViewModel
) {
    val state by viewModel.uiState.collectAsState()

    LaunchedEffect(viewModel) {
        viewModel.loadPosts()
    }

    when (val current = state) {
        PostsUiState.Loading -> {
            Column(
                modifier = Modifier.fillMaxSize(),
                verticalArrangement = Arrangement.Center
            ) {
                CircularProgressIndicator()
                Text("Loading posts...")
            }
        }

        is PostsUiState.Success -> {
            LazyColumn(
                modifier = Modifier.fillMaxSize()
            ) {
                items(
                    items = current.posts,
                    key = { post -> post.id }
                ) { post ->
                    Column(
                        modifier = Modifier
                            .fillMaxWidth()
                            .padding(16.dp)
                    ) {
                        Text(
                            text = post.title,
                            style = MaterialTheme.typography.titleMedium
                        )
                        Text(text = post.body)
                        Text(
                            text = "Post ID: ${post.id}",
                            style = MaterialTheme.typography.bodySmall
                        )
                    }
                }
            }
        }

        is PostsUiState.Error -> {
            Column(
                modifier = Modifier.padding(16.dp)
            ) {
                Text(current.message)
                Button(
                    onClick = { viewModel.loadPosts() }
                ) {
                    Text("Retry")
                }
            }
        }
    }
}

This screen assumes that the ViewModel has already been created and provided by the application. Depending on the Compose and Lifecycle versions in your project, you may prefer collectAsStateWithLifecycle() from the Lifecycle Compose library so collection follows the screen's lifecycle.

13. Sending a POST Request

GET requests retrieve data, while POST requests commonly submit data to create a resource or trigger an operation. Whether a public API accepts POST requests depends on that API's documentation.

13.1 Define a Request Model

import kotlinx.serialization.Serializable

@Serializable
data class CreatePostRequest(
    val userId: Int,
    val title: String,
    val body: String
)

13.2 Add a POST Endpoint

import retrofit2.http.Body
import retrofit2.http.POST

interface PostApi {
    @POST("posts")
    suspend fun createPost(
        @Body request: CreatePostRequest
    ): Post
}

If your project already has a PostApi interface, add this function to the existing interface rather than defining the interface twice.

13.3 Submit a Request

suspend fun submitPost(
    repository: PostRepository,
    title: String,
    body: String
): Post {
    val request = CreatePostRequest(
        userId = 1,
        title = title,
        body = body
    )

    return repository.createPost(request)
}

For the above example, add a corresponding createPost() function to the repository that delegates to api.createPost(request). JSONPlaceholder simulates resource creation; changes are not persisted like a production database.

14. HTTP Status Codes

The HTTP status code indicates the outcome of a request. Applications should distinguish successful responses from client-side and server-side errors.

These codes are common examples. The server's API documentation defines the actual behavior, error response structure, and any additional status codes.

15. Error Handling and Troubleshooting

For diagnosis, inspect the HTTP status code, response headers, and sanitized response body in a development environment. Never expose access tokens, passwords, or sensitive personal information in production logs.

16. API Keys and Security

Some public APIs require an API key even if their data is publicly available. Follow the provider's authentication and usage instructions.

• Use HTTPS for network communication.
• Never place private server credentials, database passwords, or privileged secrets directly in Android source code.
• Remember that keys embedded in an APK can often be extracted; use provider restrictions and a backend when stronger protection is required.
• Send authentication tokens using the header format documented by the API.
• Request only the data the application needs.
• Validate data on the server; client-side validation alone is not sufficient.
• Respect rate limits, attribution requirements, licensing, and terms of service.
• Do not disable TLS certificate validation to make a failing request work.
• Handle sensitive response data carefully and avoid unnecessary local storage.

17. Pagination and Large Responses

Some APIs return hundreds or thousands of records. Loading all records at once can increase memory usage and delay the user interface. Pagination allows the application to retrieve smaller batches.

Common pagination styles include:

• Page-based: Uses query parameters such as page=1 and limit=20.
• Offset-based: Uses parameters such as offset=0 and limit=20.
• Cursor-based: Uses a continuation token returned by the previous response.

Example of a page-based Retrofit endpoint:

import retrofit2.http.GET
import retrofit2.http.Query

interface PaginatedPostApi {
    @GET("posts")
    suspend fun getPostsPage(
        @Query("_page") page: Int,
        @Query("_limit") limit: Int
    ): List<Post>
}

The query parameters shown are examples for practice and may not be supported by another API. Follow the service's pagination contract. For very large feeds, consider an established pagination solution such as AndroidX Paging.

18. Testing a REST API Integration

Testing helps verify that networking, parsing, and UI behavior remain reliable when responses or connectivity change.

18.1 Test the Data Model

• Test a valid JSON response.
• Test optional fields and missing values.
• Test additional unknown fields.
• Test malformed JSON and unexpected value types.

18.2 Test the Repository

• Verify that successful API responses are returned correctly.
• Simulate network failures.
• Simulate HTTP error responses.
• Verify that errors are not incorrectly represented as successful data.

18.3 Test the UI

• Verify the loading indicator is shown during a request.
• Verify that retrieved records are displayed.
• Verify that an empty response has an appropriate empty state.
• Verify that a retry action can initiate another request.

For unit tests, use a fake repository or a mock API. For networking integration tests, use a controlled test server so that the response content and status codes are predictable.

19. Best Practices

• Use a layered architecture: Separate UI, ViewModel, repository, and network service responsibilities.
• Use typed response models: Prefer data classes over scattered manual JSON field extraction for predictable APIs.
• Keep requests asynchronous: Use Retrofit suspend functions and coroutines rather than blocking the main thread.
• Model API failures explicitly: Distinguish connectivity problems, HTTP failures, and invalid response data.
• Respect the API contract: Do not assume every API supports POST, PATCH, authentication, or pagination.
• Avoid duplicate requests: Trigger data loading through controlled state or lifecycle-aware effects.
• Use lifecycle-aware collection: Collect UI state using appropriate Lifecycle and Compose APIs.
• Handle cancellation correctly: Do not convert coroutine cancellation into an ordinary network error.
• Protect user data: Avoid logging sensitive information and minimize unnecessary transmission.
• Consider caching: Use a cache or local database when the product needs offline access or reduced network usage.
• Document dependencies: Keep plugin, runtime, Retrofit, and converter versions compatible.
• Test edge cases: Include empty responses, malformed JSON, slow connections, and server failures.

20. Practical Exercise: Public Posts Application

Objective: Build an Android application that retrieves posts from a public REST API and displays them in a list.

Requirements

1. Create a new Android Studio project using Kotlin.
2. Add the Internet permission.
3. Configure Retrofit and Kotlin Serialization.
4. Create a serializable Post data class.
5. Define a GET endpoint for retrieving posts.
6. Create a repository and ViewModel.
7. Display posts in a Compose LazyColumn.
8. Show a loading indicator while data is retrieved.
9. Display an error message when the request fails.
10. Add a retry button.
11. Add a detail screen that retrieves a post by ID.
12. Test the app with network disabled and with an invalid endpoint.

Expected Outcome

The completed application should be able to send a network request, parse JSON into Kotlin objects, display remote data, and handle common failure conditions without crashing.

21. Mini Project: Public Weather API Application

As an extension, build a weather application that retrieves weather information from a public or registered weather API.

Suggested features:

• Search weather by city name.
• Retrieve current temperature and weather conditions.
• Display humidity and wind speed when provided by the API.
• Show a loading indicator during requests.
• Handle invalid city names and rate-limit responses.
• Keep API credentials out of public source code where possible.
• Display the API provider's required attribution.
• Cache the most recent successful result if appropriate.

This project helps practise API documentation reading, query parameters, JSON model design, loading and error states, and secure handling of credentials.

22. Interview Questions and Answers

Q1. What is a REST API?

Answer: A REST API exposes resources through HTTP endpoints and uses standard HTTP methods to retrieve or modify data.

Q2. What is a public REST API?

Answer: It is an API made available for public or developer use. It may still require registration, API keys, rate-limit compliance, or acceptance of usage terms.

Q3. What is an endpoint?

Answer: An endpoint is a specific URL path and method combination through which an application accesses a resource or performs an operation.

Q4. Why is Retrofit used in Android?

Answer: Retrofit simplifies HTTP requests by letting developers declare endpoints in interfaces and use converters to map response bodies to Kotlin or Java types.

Q5. Why is Internet permission required?

Answer: The android.permission.INTERNET permission allows the app to open network sockets for communication with remote services.

Q6. What is JSON deserialization?

Answer: It converts JSON data into a Kotlin or Java object so the application can access fields through properties.

Q7. What is the difference between GET and POST?

Answer: GET commonly retrieves data, while POST commonly submits data to create a resource or initiate an operation. The exact behavior depends on the API contract.

Q8. What is the purpose of a repository?

Answer: A repository separates data-access operations from the UI and provides a consistent interface for retrieving data from network or local sources.

Q9. Why should network requests not run on the main thread?

Answer: Slow network operations on the main thread can block UI rendering and make the application unresponsive. Asynchronous APIs and coroutines avoid blocking the main thread for the request.

Q10. How should network errors be handled?

Answer: Handle connectivity failures, HTTP errors, parsing failures, and unexpected conditions separately where useful. Expose a safe message and provide retry behavior when appropriate.

Q11. What is the purpose of a Retrofit converter?

Answer: A converter transforms response bodies into application types and can serialize request objects into formats such as JSON.

Q12. Why should an app use HTTPS?

Answer: HTTPS protects data in transit through TLS and helps prevent attackers from reading or modifying network communication.

Q13. What is pagination?

Answer: Pagination retrieves large collections in smaller batches, reducing memory usage and improving the user experience.

Q14. What is an HTTP 404 response?

Answer: It indicates that the requested resource or endpoint was not found. The application should verify the URL and handle the response appropriately.

Q15. Why should API keys not be treated as secrets when embedded in an APK?

Answer: APK contents can be inspected, so embedded keys can potentially be extracted. Use provider restrictions and server-side protection for privileged credentials.

23. Quick Revision Checklist

• A REST API exposes resources through HTTP endpoints.
• Public APIs may have authentication and usage limits.
• Add Internet permission to the Android manifest.
• Use Retrofit to declare and execute HTTP requests.
• Create Kotlin data classes that match the JSON response.
• Configure an appropriate JSON converter.
• Use a repository to separate data access from the UI.
• Use a ViewModel to expose loading, success, and error states.
• Display collections efficiently with LazyColumn or RecyclerView.
• Handle HTTP errors, network failures, and parsing problems.
• Use HTTPS and protect credentials.
• Test success, empty responses, failures, and retry behavior.

24. Official Learning Resources

• Android Developers: Connect to the Network — network permissions, HTTP clients, and repository patterns.
• Android Kotlin Compose: Get Data from the Internet — a practical Retrofit and Kotlin Serialization tutorial.
• Retrofit Documentation — API interfaces, HTTP requests, and converters.
• Kotlin Serialization Documentation — JSON parsing and Kotlin serialization concepts.
• JSONPlaceholder — sample API for learning and testing.

25. Conclusion

Integrating a public REST API into an Android application enables the app to retrieve remote information and respond to changing data. A maintainable implementation uses Retrofit for networking, Kotlin data models and a JSON converter for response parsing, repositories for data access, and ViewModels to manage UI state.

Successful integration requires more than making a request. Developers should also handle loading and error states, respect API usage rules, protect credentials, use secure connections, test different response conditions, and keep network work away from the main thread.

To continue learning, explore the JustAcademy Android App Development Course, register for a course demo, or visit the JustAcademy website.