PodcastIndex-SDK
0.4.0indexedOffers a type-safe SDK for interacting with the Podcast Index API, providing authentication, logging, serialization, and search capabilities for building podcast applications.
7
Stars
—
Used by
dependents
—
Health
/ 100
PodcastIndex-SDK
Jump to: About | Download | How to use | Advanced | Roadmap | License
About
Unofficial Type-safe PodcastIndex SDK for Kotlin Multiplatform Supporting Android/Desktop/iOS platforms.
Podcast Index is a large, categorized, and free index of podcasts. It offers a REST API to access the index. This SDK is a wrapper around the API that offers idiomatic Kotlin API plus handling things like Authentication, retrying failed authenticated requests in odd scenarios, Logging, Serialization, and more for developers looking to build podcast experiences.
Download
Add the Maven Central repository if it is not already there:
repositories {
mavenCentral()
}
In Kotlin Multiplatform projects, add the dependency:
commonMain {
dependencies {
// If you're using Ktor 2
implementation("io.github.mr3y-the-programmer:podcastindex-sdk-ktor2:<latest-version>")
// Or if you're using Ktor 3
implementation("io.github.mr3y-the-programmer:podcastindex-sdk-ktor3:<latest-version>")
}
}
Or in a single-platform project:
dependencies {
// If you're using Ktor 2
implementation("io.github.mr3y-the-programmer:podcastindex-sdk-ktor2:<latest-version>")
// Or if you're using Ktor 3
implementation("io.github.mr3y-the-programmer:podcastindex-sdk-ktor3:<latest-version>")
}
Compatibility:
- Java 8+.
- Kotlin 1.9+.
- Ktor 2 & 3.
How to use
- Initialize client instance by calling
PodcastIndexClientwith your credentials:
val client = PodcastIndexClient(BuildConfig.API_KEY, BuildConfig.API_SECRET, userAgent = "MyPodcastApp/1.2")
That's it, now you're ready to start interacting with different SDK services, PodcastIndexClient function also takes an optional config lambda parameter which allows you to enable/disable some properties, See Advanced section for more details
Search Service
Search Podcasts by term: Click Here to See
// This method takes other optional parameters like limit, includeSimilar...etc that allow you to fine-tune the search result.
val result: MultiplePodcastsResult = client.search.forPodcastsByTerm(term = "android")
Search Podcasts by title: Click Here to See
// This method takes other optional parameters like limit, includeSimilar...etc that allow you to fine-tune the search result.
val result: MultiplePodcastsResult = client.search.forPodcastsByTitle(title = "Talking Kotlin")
Search Episodes by person: Click Here to See
val result: MultipleEpisodesResult = client.search.forEpisodesByPerson(name = "john doe")
Search Music Podcasts by term: Click Here to See
val result: MultiplePodcastsResult = client.search.forMusicPodcastsByTerm(term = "music")
Similarly, accessing other services/endpoints follows the same approach.
Advanced
- Enable logging to get better insights about outgoing requests which might be helpful for debugging (Default is false):
val client = PodcastIndexClient(...) {
enableLogging = if (BuildConfig.DEBUG) true else false
}
Sensitive information like API_KEY & API_SECRET are masked and won't be printed out in logs so, you can enable this safely.
- Change the default tag used for logging (Default is "PodcastIndexSDK"):
val client = PodcastIndexClient(...) {
loggingTag = "MyCustomTag"
}
- Specify the max number of retries when a request fails (Default is 3):
val client = PodcastIndexClient(...) {
maxRetries = 5
}
- Enabling/Disabling request timeout (Default is true):
val client = PodcastIndexClient(...) {
enableTimeout = false
}
- Specify the default timeout in milliseconds (Default is 10 seconds):
val client = PodcastIndexClient(...) {
defaultTimeout = 5_000L // 5 seconds
}
- Customize or choose a different HTTP client which is useful if you use a certain HTTP client instance in your app with special configuration and you want to make the SDK reuse the same instance:
val client = PodcastIndexClient(...) {
httpClient(Okhttp) {
// Customize OkHttp client configuration
engine {
preconfigured = okHttpClientInstance
}
}
}
Support table
Some endpoints are still work-in-progress and not implemented yet (⌛)
License
Copyright 2024 MR3Y
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http:
Unless applicable law agreed to writing, software
distributed under the License distributed an BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express implied.
See the License the specific language governing permissions
limitations under the License.