CPS251 Book

CPS251 Android Development by Scott Shaper

Building the WeatherApiService

The WeatherApiService file describes the weather endpoint we call with Retrofit. This interface is a contract: it tells Retrofit what URL path to use, what query parameters to send, and what Kotlin type should be returned.

interface WeatherApiService {
    @GET("data/2.5/weather")
    suspend fun getCurrentWeather(
        @Query("zip") zip: String,
        @Query("appid") appId: String,
        @Query("units") units: String = "metric"
    ): WeatherResponse
}

Code Explanation

Interface as an API Contract

interface WeatherApiService defines what operations are available for weather data.
You do not manually implement this interface; Retrofit creates the implementation at runtime.
This keeps your code simple and readable.

Endpoint Annotation

@GET("data/2.5/weather") says this function uses an HTTP GET request.
This path is appended to the base URL from RetrofitClient.
Together they form the full endpoint URL.

Suspend Function

suspend fun getCurrentWeather(...) means this function runs in a coroutine.
Network requests can take time, so we run them asynchronously to avoid freezing the UI.
The repository calls this function from coroutine-based code.

Query Parameters

@Query("zip") zip: String sends the zip code (for example, 48197,us).
@Query("appid") appId: String sends the API key needed by OpenWeatherMap.
@Query("units") units: String = "metric" sends units and defaults to metric, so temperatures return in Celsius.
Because units has a default value, callers can omit it if they want metric units.

Return Type

The function returns WeatherResponse, which is your data model for the JSON response.
Retrofit + Gson convert raw JSON into that Kotlin object automatically.
This gives type-safe data access instead of manual JSON parsing.

How It Connects to the App

RetrofitClient creates this service.
WeatherRepository calls getCurrentWeather().
WeatherViewModel handles success and failure results for the UI.
WeatherAppScreen only reads state and triggers actions.

Learning Aids

Tips for Success

Think of each function in this interface as one API endpoint.
Use clear parameter names that match what the API expects.
Keep endpoint functions suspend when they perform network I/O.
Use default parameter values when the API has a common default behavior.
Keep this file focused on endpoint definitions only.

Common Mistakes to Avoid

Misspelling query names like appid or zip.
Forgetting suspend and then calling network code on the wrong thread.
Using the wrong endpoint path in @GET.
Returning the wrong data class type that does not match the JSON structure.
Mixing business logic into this interface.

Best Practices

Keep API interfaces clean and declarative.
Use one service interface per feature area when possible.
Return strongly typed models (like WeatherResponse) for safety and readability.
Use repository classes to wrap service calls and handle errors.
Document required query parameters in comments or lesson text for teammates.