libec / ynab-kmp-api

A multiplatform Kotlin library for a public YNAB API

YNAB (You Need A Budget) is a great piece of budgeting software with a public API. This is a multiplatform Kotlin library for that API that compiles for JVM for Android and LLVM for iOS.

The feature set is not 1:1 to the public API, but it's a good starting point built on solid foundations.

Motivation

I'm an iOS developer interested in sharing code across platforms without compromising the native experience. I knew zero Kotlin before this, but learning by doing is my jam, and doing something useful like sharing data access code is a great starting point that is just a step away from sharing business logic to ensure consistency across the whole product.

Usage

Check EndToEndTests in Kotlin and in Swift for a executable example of how to use the library.

Replace null with your token (also, don't commit your access token to git):

val accessToken: String? = null

Inject your access token to start a session:

val ynabSession = YnabSession(UserAuthentication(accessToken))

Session scoped repositories hold your data for the lifetime of the session:

val budgetRepository = ynabSession.getBudgetsRepository()
val accountsRepository = ynabSession.getAccountsRepository()
val payeesRepository = ynabSession.getPayeesRepository()
val categoriesRepository = ynabSession.getCategoriesRepository()
val transactionsRepository = ynabSession.getTransactionsRepository()

Fetch your data:

budgetRepository.fetchAllBudgets()
accountsRepository.fetchAccounts(budgetId = budget.id)
payeesRepository.fetchPayees(budgetId = budget.id)
categoriesRepository.fetchCategories(budgetId = budget.id)

Subscribe to updates:

budgetRepository.budgets.map { budgets ->
    // Do your domain or presentation magic here
}

categoriesRepository.categories.map { categories ->
    // Do your domain or presentation magic here
}

Why bother with Repositories and not just expose Resources

To quote myself:

A repository is a design pattern that abstracts data access logic from business access logic by exposing the collection-like interface to access business entities. The actual implementation of the interface might communicate with the database, REST API, and what your project requires...

A repository is a great place for possible implementation of caching and compilation of delta requests as described in the public API.

ynab-kmp-api's Issues

Leverage Ktors Authentication plugin

Try to use Ktor's Authentication plugin instead of injecting tokens like it's the 90s

https://github.com/libec/ynab-kmm-api/blob/8a87ea89218d8de226e0c385f2b7928b4964a046/shared/src/commonMain/kotlin/infrastructure/networking/NetworkClient.kt#L36-L40

Improve gradle setup

Gradle setup is rough around the edges and it now looks like it was bootstraped by an iOS developer (it definitely was).

1. Move lib declarations and their versions to libs.versions.toml at least.
2. Modularize the packages properly so that commonTests structure matches commonMain

Replaces Koin's get() get() get()

Take a look to see if there's another way to register services, as get() get() get() feels a bit odd.

https://github.com/libec/ynab-kmm-api/blob/8a87ea89218d8de226e0c385f2b7928b4964a046/shared/src/commonMain/kotlin/scopes/Scopes.kt#L38-L62

Late ktor json plugin installation fails for iOS

Installing the JSON plugin to Ktor HttpClient after it's been initialized doesn't seem to take effect on iOS resulting in parsing failure.

Installing the JSON plugin directly in HttpClient's initializer block works fine:
https://github.com/libec/ynab-kmm-api/blob/f29a2afdb96b15b9a1d2e21dd0a031436db22a52/shared/src/commonMain/kotlin/scopes/Scopes.kt#L52-L60

HttpClient {
    install(ContentNegotiation) {
        json(makeJsonNegotiation())
    }
}

Registering HttpClient in Koin and installing JSON plugin later in NetworkClient's init cases parsing failures on iOS

factory<HttpClient> { HttpClient() }

https://github.com/libec/ynab-kmm-api/blob/f29a2afdb96b15b9a1d2e21dd0a031436db22a52/shared/src/commonMain/kotlin/infrastructure/networking/NetworkClient.kt#L17-L27

Remove java.io.File dependency from shared tests

Tests for the shared code can't run on iOS.

1. Check if it makes sense to remove java.io.File and use https://github.com/Kotlin/kotlinx-io instead.
2. Check if anyone runs KMP tests on iOS as mocking and the JVM environment might come in handy later

https://github.com/libec/ynab-kmm-api/blob/8a87ea89218d8de226e0c385f2b7928b4964a046/shared/src/commonTest/kotlin/mocks/HttpClientMockFactory.kt#L50-L56