Diskogs - API wrapper for Discogs in Kotlin Multiplatform

It's not a typo!

Diskogs is a kotlin multiplatform project supporting the following targets:

JVM (8 or later) and Android (API level 22 or later)
JavaScript
Native, although probably not iOS

Todo

json mode
better fault handling
mock api testing
usage guide
rate limit handling

Implemented endpoint groups

Get started

Gradle

build.gradle.kts:

dependencies {
    implementation("me.riberr.diskogs:Diskogs:$DiskogsVersion")
    
    // Choose an engine that supports your target(s):
    // https://ktor.io/clients/http-client/engines.html
    // The version should match the version Diskogs is using
    implementation("io.ktor:ktor-client-cio:$KtorVersion")
}

Usage

Create your client:

val diskogs = Diskogs.create("MyUserAgent/1.0")

As per Discogs documentation, your application must provide a user-agent that identifies itself. Make it unique and preferably follow RFC 1945.

Make some requests:

// All endpoints return value or throwable encapsulated in Result<>
diskogs.database.getArtist(666)
        .onSuccess { println(it) }
        .onFailure { error(it) }

// Another style
val artist = diskogs.database.getArtist(666).getOrThrow()

Some endpoints supports pagination:

diskogs.database.getArtistReleases(666, ArtistReleases.Sort.TITLE, page = 0, perPage = 20)
    .onSuccess { it.releases.forEach { release -> release.title } }
    .onFailure { error(it) }

Log level

It is possible to set the log level of the ktor client upon creating the diskogs client:

val diskogs = Diskogs.create(
            "MyUserAgent/1.0",
            logLevel = LogLevel.ALL
        )

Authorizing with OAuth flow

The following example shows how to authorize using OAuth 1.0:

// This particular example is written in kotlin/jvm 
suspend fun main(args: Array<String>) {
    // Your application must provide a User-Agent string that identifies itself
    val userAgent: String = args[0]

    // Application registration can be found here: https://www.discogs.com/settings/developers
    val consumerKey: String = args[1]
    val consumerSecret: String = args[2]

    // Request token expires after 15 min
    val requestToken = Diskogs.requestTokenOauth(userAgent, consumerKey, consumerSecret)
        .getOrElse { error(it) }
    println("requestToken: $requestToken")

    // This page will ask the user to authorize your app on behalf of their Discogs account.
    // If they accept and authorize, they will receive a verifier key to use as verification
    println("browse to ${requestToken.oauthAuthUrl} and input verifier key")
    print("Verifier key: ")
    val verifierKey: String = readLine() ?: throw Exception("user must input verifier key")

    //  These tokens do not expire (unless the user revokes access from your app),
    //  so you should persist these tokens to make future requests signed with OAuth
    val accessToken = Diskogs.accessTokenOauth(
        userAgent, consumerKey, consumerSecret, requestToken, verifierKey
    ).getOrElse { error(it) }
    println("accessToken: $accessToken")

    // Create the client that will be used for all future requests to discogs endpoints
    val diskogs = Diskogs.create(userAgent, consumerKey, consumerSecret, accessToken)

    // Example request
    diskogs.user.getIdentity()
        .onSuccess {
            println("user id: ${it.id}")
            println("user name: ${it.username}")
            println("user url: ${it.resourceUrl}")
        }
}

For more information, see: https://www.discogs.com/developers#page:authentication,header:authentication-discogs-auth-flow

Resources

https://www.discogs.com/developers#page:home
https://ktor.io/docs/welcome.html

voboshi / Diskogs