Project: Amphibians app

1. Before you begin

This codelab introduces a new app called Amphibians that you'll build on your own. This codelab walks you through the steps to complete the Amphibians app project, including project setup and testing within Android Studio.

Prerequisites

  • This project is for users who have completed Unit 4 of the Android Basics in Kotlin course.

What you'll build

  • Implement networking in an app using Retrofit and Moshi and appropriate error handling.

What you'll need

  • A computer with Android Studio installed.

2. Finished app overview

Welcome to Project: Amphibians!

Up until this point all the apps you've built have relied on data stored locally. This time, you'll take an app that displays information about different amphibian species, and use your knowledge of networking, JSON parsing, and view models to enable the app to use data from the network. The app will get its data from a custom API for this project and display it in a list view.

In the final app, the first screen the user will see displays the names of each species in a recycler view.

7697a4e0c9bb5a76.png

Tapping a list item navigates to the detail screen which also displays the species' name as well as a detailed description.

9797605a20dc68d1.png

While the UI portion of this app is already built for you, running the starter project won't show any data. You'll need to implement the networking portion of the app, and then show the downloaded data in the layout.

3. Get started

Download the project code

Note that the folder name is android-basics-kotlin-amphibians-app. Select this folder when you open the project in Android Studio.

To get the code for this codelab and open it in Android Studio, do the following.

Get the code

  1. Click on the provided URL. This opens the GitHub page for the project in a browser.
  2. On the GitHub page for the project, click the Code button, which brings up a dialog.

5b0a76c50478a73f.png

  1. In the dialog, click the Download ZIP button to save the project to your computer. Wait for the download to complete.
  2. Locate the file on your computer (likely in the Downloads folder).
  3. Double-click the ZIP file to unpack it. This creates a new folder that contains the project files.

Open the project in Android Studio

  1. Start Android Studio.
  2. In the Welcome to Android Studio window, click Open an existing Android Studio project.

36cc44fcf0f89a1d.png

Note: If Android Studio is already open, instead, select the File > New > Import Project menu option.

21f3eec988dcfbe9.png

  1. In the Import Project dialog, navigate to where the unzipped project folder is located (likely in your Downloads folder).
  2. Double-click on that project folder.
  3. Wait for Android Studio to open the project.
  4. Click the Run button 11c34fc5e516fb1c.png to build and run the app. Make sure it builds as expected.
  5. Browse the project files in the Project tool window to see how the app is set-up.

Implement the API service

Like in previous projects, most of the app is already implemented for you. You just need to implement the networking portion using what you learned in Unit 4. Feel free to familiarize yourself with the starter code. Most of the concepts should already be familiar from Units 1 to 3. The following steps call out specific parts of the code where necessary to complete each step.

The app displays a list of amphibian data from the network. The amphibian data comes from a JSON object returned by the API. Take a look at the Amphibian.kt file in the network package. This class models a single amphibian object, a list of which will be returned from the API. Each amphibian has three properties: a name, type, and description.

data class Amphibian(
    val name: String,
    val type: String,
    val description: String
)

The backend for this API is fairly simple. There are two key pieces of information you'll need to access the amphibians data: a base URL and an endpoint to get the list of amphibians.

  1. Base URL: https://developer.android.com/courses/pathways/android-basics-kotlin-unit-4-pathway-2/
  2. GET amphibians list: android-basics-kotlin-unit-4-pathway-2-project-api.json

The project already has the Retrofit and Moshi dependencies. In the network package, you'll find the AmphibianApiService.kt file. The file contains several TODO comments. Perform the following five tasks to implement the amphibians app.:

  1. Create a variable to store the API's base URL.
  2. Build the Moshi object with Kotlin adapter factory that Retrofit will be using to parse JSON.
  3. Build aRetrofit instance using the Moshi converter.
  4. Implement the AmphibianApiService interface with a suspend function for each API method (for this app, there's only one method, to GET the list of amphibians).
  5. Create an AmphibianApi object to expose a lazy-initialized Retrofit service that uses the AmphibianApiService interface.

Implement the ViewModel

Once your API is implemented, you'll make the request to the amphibians API and store any values that need to be displayed. You'll do this in the AmphibianViewModel.kt class found in the ui package.

You'll notice that above the class declaration is an enum called AmphibianApiStatus.

enum class AmphibianApiStatus {LOADING, ERROR, DONE}

The three possible values, LOADING, ERROR and DONE, are used to show the status of the request to the user.

In the AmphibianViewModel.kt class itself, you'll need to implement some LiveData variables, a function to interact with the API, and a function to handle setting the amphibian on the detail screen.

  1. Add a _status a private MutableLiveData variable that can hold an AmphibianApiStatus enum and backing property status for the status.
  2. Add an amphibians variable and private backing property _amphibians for the list of amphibians, of type List<Amphibian>.
  3. Add an _amphibian variable of type MutableLiveData<Amphibian> and backing property amphibian for the selected amphibian object, of type LiveData<Amphibian>. This will be used to store the selected amphibian shown on the detail screen.
  4. Define a function called getAmphibianList(). Launch a coroutine using ViewModelScope, inside the coroutine, perform a GET request to download the amphibian data by calling the getAmphibians() method of the Retrofit service. You'll need to use try and catch to appropriately handle errors. Before making the request, set the value of the _status to AmphibianApiStatus.LOADING . A successful request should set _amphibians to the list of amphibians from the server and set the _status to AmphibianApiStatus.DONE. In the event of an error, _amphibians should be set to an empty list and the _status set to AmphibianApiStatus.ERROR.
  5. Implement the onAmphibianClicked() method to set the _amphibian property you defined to the amphibian argument passed into the function. This method is already called when an amphibian is selected, so that it will be displayed on the detail screen.

Update the UI from the ViewModel

After implementing the ViewModel, all that's left to do is edit the fragment classes and layout files to use the data bindings.

  1. The ViewModel is already referenced in AmphibianListFragment. In the onCreateView() method, after the layout is inflated, simply call the getAmphibianList() method from the ViewModel.
  2. In the fragment_amphibian_list.xml, the <data> tags for the data binding variables have already been added to the layout files. You just need to implement the TODOs for the UI to update based on the view model. Set the appropriate bindings for the listData and apiStatus.
  3. In fragment_amphibian_detail.xml, implement the TODOs to set the appropriate text properties for the amphibian's name and description.

4. Testing instructions

Running your tests

To run your tests, you can do one of the following.

For a single test case, open up a test case class and click the green arrow to the left of the class declaration. You can then select the Run option from the menu. This will run all of the tests in the test case.

a32317d35c77142b.png

Often you'll only want to run a single test, for example, if there's only one failing test and the other tests pass. You can run a single test just as you would the entire test case. Use the green arrow and select the Run option.

ac6244434cfafb60.png

If you have multiple test cases, you can also run the entire test suite. Just like running the app, you can find this option on the Run menu.

7a925c5e196725bb.png

Note that Android Studio will default to the last target that you ran (app, test targets, etc.) so if the menu still says Run > Run ‘app', you can run the test target, by selecting Run > Run.

ee1e227446c536fe.png

Then choose the test target from the popup menu.

d570c947769db65c.png

The results of running the tests are shown on the Run tab. In the pane on the left, you'll see a list of failing tests, if any. Failing tests are marked with a red exclamation point next to the function name. Passing tests are marked with a green check mark.

6d68f2bf589501ae.png

If a test fails, the text output provides information to help you fix the problem that caused the test to fail.

92f3c8219c03651d.png

For example, in the above error message, the test is checking if a TextView is using a specific string resource. However, the test is failing. The text after "Expected" and "Got" do not match, meaning the value the test expected does not match the value from the running app. In this example, the string used in the TextView is not in-fact squeeze_count, as the test expects.