Kotlin Spotify Web API Wrapper (KMP)

Spotify Web API wrapper for Kotlin Multiplatform.

This repository provides a type-safe, coroutine-friendly Spotify API client for Kotlin, Android, iOS, JVM, and JS.

Why This Library

• Kotlin-first Spotify Web API wrapper for KMP projects
• Type-safe request/response models with kotlinx.serialization
• Coroutine-based API calls with Ktor client
• Shared business logic across Android, iOS, JVM, and JS

Status

• Supported platforms: Android, iOS(not test yet), JVM, JS (Kotlin Multiplatform)
• Basic API
  • Albums
  • Artists
  • Audiobooks
  • Categories
  • Chapters
  • Episodes
  • Genres
  • Libraries
  • Markets
  • Player
  • Playlists
  • Search
  • Shows
  • Tracks
  • Users
• Auth API
  • PKCE
  • Client Credentials
  • Authorization Code
  • Refresh
• Paging helpers / Rate limit handling / Retry policies
• Samples + Docs
• Tests

Installation (Maven Central)

Dependency coordinates:

• Group: io.github.nubasu
• Artifact: kotlin-spotify-web-api-wrapper

Recommendation : libs.versions.toml (Version Catalog)

gradle/libs.versions.toml:

[versions]
kotlinSpotifyWebApiWrapper = "0.1.0"

[libraries]
kotlin-spotify-web-api-wrapper = { module = "io.github.nubasu:kotlin-spotify-web-api-wrapper", version.ref = "kotlinSpotifyWebApiWrapper" }

build.gradle.kts:

repositories {
    mavenCentral()
}

commonMain.dependencies {
  implementation(libs.kotlin.spotify.web.api.wrapper)
}

build.gradle.kts (Kotlin DSL)

repositories {
    mavenCentral()
}

commonMain.dependencies {
    implementation("io.github.nubasu:kotlin-spotify-web-api-wrapper:0.1.0")
   
}

build.gradle (Groovy DSL)

repositories {
    mavenCentral()
}

dependencies {
    implementation 'io.github.nubasu:kotlin-spotify-web-api-wrapper:0.1.0'
}

Features

• Spotify Web API coverage for albums, artists, playlists, player, tracks, users, and more
• Authorization flows: Authorization Code with PKCE, Authorization Code, Client Credentials, Refresh Token
• Pagination helpers, rate-limit handling, and retry support
• Unit-tested non-private functions
• Sample app and docs for end-to-end auth-to-API usage

Documentation

• API reference (GitHub Pages): https://nubasu.github.io/Kotlin-Spotify-Web-API-Wrapper
• Docs index: docs/README.md
• API samples by domain: docs/samples/apis
• Flow samples: docs/samples/flows
  • Auth to API: docs/samples/flows/auth-to-api.md
  • Authorization Code to API: docs/samples/flows/authorization-code-to-api.md
  • Client Credentials to API: docs/samples/flows/client-credentials-to-api.md
  • Refresh token: docs/samples/flows/refresh-token.md
• Getting started: docs/guides/getting-started.md
• Response/error handling: docs/guides/response-and-error-handling.md
• Paging/RateLimit/Retry guide: docs/guides/paging-rate-limit-retry.md
• Token management: docs/guides/token-management.md
• Troubleshooting: docs/guides/troubleshooting.md

Sample App (composeApp)

• A sample app is included in composeApp/.
• It supports: PKCE auth -> load current user's playlists -> start/pause playback.
• Android callback deep link: spotifyauth://callback (configure this in Spotify Dashboard redirect URIs).
• JVM/Desktop auto callback: http://127.0.0.1:8888/callback (configure this in Spotify Dashboard redirect URIs).
• Desktop/JVM: run ./gradlew :composeApp:run.

Quick Start

import com.nubasu.spotify.webapi.wrapper.api.authorization.SpotifyAuthManager
import com.nubasu.spotify.webapi.wrapper.api.albums.AlbumsApis

val auth = SpotifyAuthManager(
    clientId = "YOUR_CLIENT_ID",
    redirectUri = "your.app://callback"
)

val pkce = auth.startPkceAuthorizationAndLaunch(scope = listOf("user-read-email"))
// Android/iOS: prefer in-app authentication UI, otherwise open the browser

val albumsApi = AlbumsApis()
val album = albumsApi.getAlbum("album-id")

References

• Spotify Web API reference: https://developer.spotify.com/documentation/web-api/reference
• Spotify Authorization concepts: https://developer.spotify.com/documentation/web-api/concepts/authorization

Contributing

PRs/issues are welcome.

• If you find a bug: open an issue with steps to reproduce.
• If you want to add an endpoint: follow existing conventions and include tests.
• If you add any features: open an issue or open PR!