Erik C. Thauvin
37517a2845
Bumped Kotlin to version 2.1.0 Bumped Kotlin extension to version 1.0.3 Bumped Dokka extension to version 1.0.2 Bumped JUnit to 5.11.4 Bumped UrlEncoder to version 1.6.0
186 lines
6 KiB
Markdown
186 lines
6 KiB
Markdown
[](https://opensource.org/licenses/BSD-3-Clause)
|
|
[](https://kotlinlang.org/)
|
|
[](https://rife2.com/bld)
|
|
[](https://github.com/ethauvin/jokeapi/releases/latest)
|
|
[](https://central.sonatype.com/artifact/net.thauvin.erik/jokeapi)
|
|
[](https://oss.sonatype.org/content/repositories/snapshots/net/thauvin/erik/jokeapi/)
|
|
|
|
[](https://sonarcloud.io/dashboard?id=ethauvin_jokeapi)
|
|
[](https://github.com/ethauvin/jokeapi/actions/workflows/bld.yml)
|
|
[](https://circleci.com/gh/ethauvin/jokeapi/tree/master)
|
|
|
|
# JokeAPI for Kotlin, Java and Android
|
|
|
|
A simple library to retrieve jokes from [Sv443's JokeAPI](https://v2.jokeapi.dev/).
|
|
|
|
## Examples (TL;DR)
|
|
|
|
```kotlin
|
|
import net.thauvin.erik.jokeapi.getJoke
|
|
|
|
val joke = joke()
|
|
val safe = joke(safe = true)
|
|
val pun = joke(categories = setOf(Category.PUN))
|
|
```
|
|
The parameters match the [joke endpoint](https://v2.jokeapi.dev/#joke-endpoint).
|
|
|
|
A `Joke` class instance is returned, matching the [response](https://v2.jokeapi.dev/joke/Any?type=single):
|
|
|
|
```kotlin
|
|
data class Joke(
|
|
val category: Category,
|
|
val type: Type,
|
|
val joke: List<String>,
|
|
val flags: Set<Flag>,
|
|
val id: Int,
|
|
val safe: Boolean,
|
|
val lang: Language
|
|
)
|
|
```
|
|
- View more [examples](https://github.com/ethauvin/jokeapi/blob/master/src/test/kotlin/net/thauvin/erik/jokeapi/GetJokeTest.kt#L64)...
|
|
|
|
To retrieve multiple jokes:
|
|
|
|
```kotlin
|
|
val frenchJokes = jokes(amount = 2, type = Type.TWOPART, lang = Language.FR)
|
|
frenchJokes.forEach {
|
|
println(it.joke.joinToString("\n"))
|
|
println("-".repeat(46))
|
|
}
|
|
```
|
|
|
|
- View more [examples](https://github.com/ethauvin/jokeapi/blob/master/src/test/kotlin/net/thauvin/erik/jokeapi/GetJokesTest.kt#L52)...
|
|
|
|
|
|
If an error occurs, a `JokeException` is thrown, matching the [JokeAPI errors](https://sv443.net/jokeapi/v2/#errors):
|
|
|
|
```kotlin
|
|
class JokeException(
|
|
val internalError: Boolean,
|
|
val code: Int,
|
|
message: String,
|
|
val causedBy: List<String>,
|
|
val additionalInfo: String,
|
|
val timestamp: Long,
|
|
cause: Throwable? = null
|
|
) : Exception(message, cause)
|
|
```
|
|
|
|
If an HTTP error occurs an `HttpErrorException` is thrown, with its message and cause matching the [JokeAPI status codes](https://sv443.net/jokeapi/v2/#status-codes):
|
|
|
|
```kotlin
|
|
class HttpErrorException(
|
|
val statusCode: Int,
|
|
message: String,
|
|
cause: Throwable? = null
|
|
) : IOException(message, cause)
|
|
```
|
|
- View more [examples](https://github.com/ethauvin/jokeapi/blob/master/src/test/kotlin/net/thauvin/erik/jokeapi/ExceptionsTest.kt#L57)...
|
|
|
|
## Java
|
|
|
|
To make it easier to use the library with Java, a configuration builder is available:
|
|
|
|
```java
|
|
var config = new JokeConfig.Builder()
|
|
.type(Type.SINGLE)
|
|
.safe(true)
|
|
.build();
|
|
var joke = JokeApi.joke(config);
|
|
joke.getJoke().forEach(System.out::println);
|
|
```
|
|
|
|
## bld
|
|
|
|
To use with [bld](https://rife2.com/bld), include the following dependency in your build file:
|
|
|
|
```java
|
|
repositories = List.of(MAVEN_CENTRAL);
|
|
|
|
scope(compile)
|
|
.include(dependency("net.thauvin.erik:jokeapi:0.9.1"));
|
|
```
|
|
Be sure to use the [bld Kotlin extension](https://github.com/rife2/bld-kotlin) in your project.
|
|
|
|
## Gradle, Maven, etc.
|
|
To use with [Gradle](https://gradle.org/), include the following dependency in your build file:
|
|
|
|
```gradle
|
|
repositories {
|
|
mavenCentral()
|
|
maven { url = uri("https://oss.sonatype.org/content/repositories/snapshots") } // only needed for SNAPSHOT
|
|
}
|
|
|
|
dependencies {
|
|
implementation("net.thauvin.erik:jokeapi:0.9.1")
|
|
}
|
|
```
|
|
|
|
Instructions for using with Maven, Ivy, etc. can be found on [Maven Central](https://central.sonatype.com/artifact/net.thauvin.erik/jokeapi).
|
|
|
|
## Raw Jokes
|
|
|
|
You can also retrieve one or more raw (unprocessed) jokes in all [supported formats](https://jokeapi.dev/#format-param).
|
|
|
|
For example for YAML:
|
|
```kotlin
|
|
var joke = getRawJokes(format = Format.YAML, idRange = IdRange(22))
|
|
println(joke)
|
|
```
|
|
```yaml
|
|
error: false
|
|
category: "Programming"
|
|
type: "single"
|
|
joke: "If Bill Gates had a dime for every time Windows crashed ... Oh wait, he does."
|
|
flags:
|
|
nsfw: false
|
|
religious: false
|
|
political: false
|
|
racist: false
|
|
sexist: false
|
|
explicit: false
|
|
id: 22
|
|
safe: true
|
|
lang: "en"
|
|
|
|
```
|
|
- View more [examples](https://github.com/ethauvin/jokeapi/blob/master/src/test/kotlin/net/thauvin/erik/jokeapi/GetRawJokesTest.kt#L46)...
|
|
|
|
## Extending
|
|
|
|
A generic `apiCall()` function is available to access other [JokeAPI endpoints](https://v2.jokeapi.dev/#endpoints).
|
|
|
|
For example to retrieve the French [language code](https://v2.jokeapi.dev/#langcode-endpoint):
|
|
|
|
```kotlin
|
|
val lang = JokeApi.apiCall(
|
|
endPoint = "langcode",
|
|
path = "french",
|
|
params = mapOf(Parameter.FORMAT to Format.YAML.value)
|
|
)
|
|
println(lang)
|
|
```
|
|
```yaml
|
|
error: false
|
|
code: "fr"
|
|
```
|
|
- View more [examples](https://github.com/ethauvin/jokeapi/blob/master/src/test/kotlin/net/thauvin/erik/jokeapi/ApiCallTest.kt#L48)...
|
|
|
|
## Contributing
|
|
|
|
If you want to contribute to this project, all you have to do is clone the GitHub
|
|
repository:
|
|
|
|
```console
|
|
git clone git@github.com:ethauvin/jokeapi.git
|
|
```
|
|
|
|
Then use [bld](https://rife2.com/bld) to build:
|
|
|
|
```console
|
|
cd jokeapi
|
|
./bld compile
|
|
```
|
|
|
|
The project has an [IntelliJ IDEA](https://www.jetbrains.com/idea/) project structure. You can just open it after all
|
|
the dependencies were downloaded and peruse the code.
|