Building a Wallpaper App That Fetches From an API

title: "Building a Wallpaper App That Fetches From an API" date: "2024-07-20" description: "Building an Android wallpaper app with Kotlin that fetches high-resolution images from a REST API, implements local caching with Room, and sets wallpapers programmatically." tags: ["kotlin", "android", "api"] published: true image: ""

Wallpaper apps are a surprisingly good learning project. They seem simple — fetch images, display them, set them — but each step has genuine complexity: API rate limits, large file downloads, offline behaviour, and a system API (WallpaperManager) that behaves differently depending on the Android version and launcher. This was my first Android project that involved all three of networking, local persistence, and a system service at the same time.

Project Overview

The app lets users browse a grid of wallpapers fetched from a free API, preview them full-screen, mark favourites that persist offline, and apply any wallpaper to the home screen or lock screen (or both). The tech stack is deliberately different from my Compose gallery app — this uses Views and RecyclerView rather than Compose, which meant working with adapters and DiffUtil instead of lazy lists.

The main components:

Component	Technology
Networking	Retrofit 2 + OkHttp
Image loading	Coil
Local database	Room
Async work	Kotlin Coroutines + Flow
DI	Manual (no Hilt)
Layout	RecyclerView + StaggeredGridLayoutManager

API Integration With Retrofit

The wallpaper API follows a structure similar to Unsplash — paginated endpoints returning JSON arrays of photo objects with URLs for different resolutions:

data class WallpaperDto(
    @Json(name = "id")           val id: String,
    @Json(name = "description")  val description: String?,
    @Json(name = "urls")         val urls: WallpaperUrls,
    @Json(name = "likes")        val likes: Int,
    @Json(name = "user")         val photographer: PhotographerDto
)
 
data class WallpaperUrls(
    @Json(name = "raw")     val raw: String,
    @Json(name = "full")    val full: String,
    @Json(name = "regular") val regular: String,
    @Json(name = "small")   val small: String,
    @Json(name = "thumb")   val thumb: String
)
 
interface WallpaperApiService {
    @GET("photos")
    suspend fun getWallpapers(
        @Query("page")     page: Int = 1,
        @Query("per_page") perPage: Int = 20,
        @Query("order_by") orderBy: String = "popular"
    ): List<WallpaperDto>
 
    @GET("photos/{id}")
    suspend fun getWallpaperDetail(@Path("id") id: String): WallpaperDto
 
    @GET("search/photos")
    suspend fun searchWallpapers(
        @Query("query")    query: String,
        @Query("page")     page: Int = 1,
        @Query("per_page") perPage: Int = 20
    ): SearchResultDto
}

The Retrofit instance is built with an OkHttpClient that handles auth headers and sets sensible timeouts:

object RetrofitProvider {
    private val okHttpClient = OkHttpClient.Builder()
        .addInterceptor { chain ->
            val request = chain.request().newBuilder()
                .addHeader("Authorization", "Client-ID ${BuildConfig.UNSPLASH_ACCESS_KEY}")
                .build()
            chain.proceed(request)
        }
        .connectTimeout(30, TimeUnit.SECONDS)
        .readTimeout(60, TimeUnit.SECONDS) // larger for high-res downloads
        .build()
 
    val service: WallpaperApiService = Retrofit.Builder()
        .baseUrl("https://api.unsplash.com/")
        .client(okHttpClient)
        .addConverterFactory(MoshiConverterFactory.create())
        .build()
        .create(WallpaperApiService::class.java)
}

The API key lives in BuildConfig sourced from local.properties, not hardcoded in source. This is table stakes — never commit API keys.

Image Loading With Coil

For the grid, I load thumbnails at reduced quality. For the preview screen, I load the regular size (~1080px wide), and only switch to full when the user taps "apply":

// In the RecyclerView adapter
fun bind(wallpaper: WallpaperItem) {
    binding.ivThumbnail.load(wallpaper.urls.small) {
        crossfade(true)
        placeholder(R.drawable.placeholder_wallpaper)
        error(R.drawable.error_wallpaper)
        size(ViewSizeResolver(binding.ivThumbnail))
    }
}
 
// In the preview activity
fun loadPreview(urls: WallpaperUrls) {
    binding.ivPreview.load(urls.regular) {
        crossfade(300)
        listener(
            onSuccess = { _, _ -> binding.progressBar.isVisible = false },
            onError   = { _, _ -> showErrorSnackbar() }
        )
    }
}

Coil's disk cache is enabled by default, which means scrolling back through previously loaded wallpapers doesn't re-fetch from the network. For a wallpaper app where images are large and bandwidth-expensive, this is not optional.

One thing I got wrong early on: I was using binding.ivPreview.load(urls.full) on the preview screen. The full URL returns the original resolution — sometimes 5000×7000px. Loading that into a preview screen for display purposes is wasteful and slow. Switching to regular made the preview load in 1–2 seconds instead of 10+.

Room for Favourites

The Favourite entity is minimal — I store only what's needed to display the wallpaper offline, not the full DTO:

@Entity(tableName = "favourites")
data class FavouriteEntity(
    @PrimaryKey val id: String,
    val thumbUrl: String,
    val regularUrl: String,
    val fullUrl: String,
    val description: String?,
    val photographerName: String,
    val savedAt: Long = System.currentTimeMillis()
)
 
@Dao
interface FavouriteDao {
    @Query("SELECT * FROM favourites ORDER BY savedAt DESC")
    fun getAllFavourites(): Flow<List<FavouriteEntity>>
 
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun insert(favourite: FavouriteEntity)
 
    @Query("DELETE FROM favourites WHERE id = :id")
    suspend fun deleteById(id: String)
 
    @Query("SELECT EXISTS(SELECT 1 FROM favourites WHERE id = :id)")
    suspend fun isFavourited(id: String): Boolean
}

Returning Flow<List<FavouriteEntity>> from the DAO rather than a plain List means the UI automatically updates when a favourite is added or removed — no manual refresh logic needed. The ViewModel collects this flow:

class FavouritesViewModel(private val dao: FavouriteDao) : ViewModel() {
    val favourites: StateFlow<List<FavouriteEntity>> = dao
        .getAllFavourites()
        .stateIn(
            scope = viewModelScope,
            started = SharingStarted.WhileSubscribed(5000),
            initialValue = emptyList()
        )
 
    fun toggleFavourite(wallpaper: WallpaperItem) {
        viewModelScope.launch {
            if (dao.isFavourited(wallpaper.id)) {
                dao.deleteById(wallpaper.id)
            } else {
                dao.insert(wallpaper.toFavouriteEntity())
            }
        }
    }
}

Setting Wallpapers Programmatically

WallpaperManager is the system API for setting wallpapers. The tricky part is that setting a wallpaper requires decoding a potentially large bitmap, which must happen off the main thread, and you have to handle the case where the download itself is still in progress:

fun applyWallpaper(
    context: Context,
    imageUrl: String,
    target: WallpaperTarget // HOME, LOCK, BOTH
) {
    CoroutineScope(Dispatchers.IO).launch {
        try {
            val loader = context.imageLoader
            val request = ImageRequest.Builder(context)
                .data(imageUrl)
                .allowHardware(false) // hardware bitmaps can't be read
                .build()
 
            val result = loader.execute(request)
            val bitmap = (result as? SuccessResult)?.drawable?.toBitmap()
                ?: throw IOException("Failed to decode bitmap")
 
            val wallpaperManager = WallpaperManager.getInstance(context)
 
            when (target) {
                WallpaperTarget.HOME ->
                    wallpaperManager.setBitmap(bitmap, null, true,
                        WallpaperManager.FLAG_SYSTEM)
                WallpaperTarget.LOCK ->
                    wallpaperManager.setBitmap(bitmap, null, true,
                        WallpaperManager.FLAG_LOCK)
                WallpaperTarget.BOTH -> {
                    wallpaperManager.setBitmap(bitmap, null, true,
                        WallpaperManager.FLAG_SYSTEM or WallpaperManager.FLAG_LOCK)
                }
            }
 
            withContext(Dispatchers.Main) {
                Toast.makeText(context, "Wallpaper set!", Toast.LENGTH_SHORT).show()
            }
        } catch (e: Exception) {
            withContext(Dispatchers.Main) {
                Toast.makeText(context, "Failed to set wallpaper", Toast.LENGTH_SHORT).show()
            }
        }
    }
}

The allowHardware(false) flag is necessary because Coil by default may decode into a HardwareBitmap, which lives in GPU memory and cannot be read by WallpaperManager. Without this, you get a java.lang.IllegalArgumentException: Software rendering doesn't support hardware bitmaps at runtime.

The FLAG_SYSTEM and FLAG_LOCK constants for targeting home vs lock screen were added in API 24. On older devices, setBitmap() without flags sets both simultaneously — something to document in your manifest's <uses-sdk>.

Pagination

For the main grid, I implemented simple cursor-based pagination with a manual "load more" trigger. Jetpack Paging 3 exists for this, but I wanted to understand the mechanics before using an abstraction:

class WallpaperRepository(private val api: WallpaperApiService) {
    private var currentPage = 1
    private var isLoading = false
    private var hasMore = true
 
    private val _wallpapers = MutableStateFlow<List<WallpaperItem>>(emptyList())
    val wallpapers: StateFlow<List<WallpaperItem>> = _wallpapers.asStateFlow()
 
    suspend fun loadNextPage() {
        if (isLoading || !hasMore) return
        isLoading = true
        try {
            val newItems = api.getWallpapers(page = currentPage, perPage = 20)
                .map { it.toDomainModel() }
            if (newItems.isEmpty()) {
                hasMore = false
            } else {
                _wallpapers.value = _wallpapers.value + newItems
                currentPage++
            }
        } finally {
            isLoading = false
        }
    }
}

The RecyclerView triggers loadNextPage() via a scroll listener when the user reaches the last 5 items. It works, but the Paging 3 library handles edge cases (network errors, retry logic, placeholder items) much more robustly. I'd use it for anything production-facing.

What I Learned About API-Driven Apps

Throttle your API calls. Free API tiers have rate limits. I hit the Unsplash limit during testing by rapid-scrolling through the grid and triggering a new page load every second. Adding a debounce on the scroll listener fixed it.

Use the right image size for the right context. Thumb for grid, regular for preview, full only for the actual wallpaper set operation. This seems obvious in retrospect but the temptation to "just use the full URL everywhere" is real when you first get it working.

Flow from Room makes favourite-state synchronisation trivial. The heart icon on each grid item reflects the correct state automatically because it's driven by a database query that emits on every change. Before I switched to Flow, I was manually refreshing the adapter after every insert/delete, which was fragile.

Writing the pagination manually before using Paging 3 was the right call. I now understand what the library is doing underneath, which makes debugging much easier when things go wrong.

The app ended up being one of the more complete projects I built during my academic years — it has networking, caching, a local database, system API integration, and pagination all working together. Each of those pieces is straightforward in isolation; getting them to work cleanly together requires thinking carefully about data flow and threading.