https://github.com/ethauvin/jokeapi
Retrieve jokes from Sv443's JokeAPI
https://github.com/ethauvin/jokeapi
android java joke jokeapi jokes jokes-api kotlin
Last synced: 5 months ago
JSON representation
Retrieve jokes from Sv443's JokeAPI
- Host: GitHub
- URL: https://github.com/ethauvin/jokeapi
- Owner: ethauvin
- License: bsd-3-clause
- Created: 2022-09-23T07:57:43.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2025-04-26T02:33:03.000Z (6 months ago)
- Last Synced: 2025-04-26T03:38:55.357Z (6 months ago)
- Topics: android, java, joke, jokeapi, jokes, jokes-api, kotlin
- Language: Kotlin
- Homepage:
- Size: 563 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
[](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.joke
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,
val flags: Set,
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,
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, SONATYPE_SNAPSHOTS_LEGACY);
scope(compile)
.include(dependency("net.thauvin.erik", "jokeapi", "1.0.0"));
```
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:1.0.0")
}
```
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 jokes = getRawJokes(format = Format.YAML, idRange = IdRange(22))
println(jokes.data)
```
```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 response = JokeApi.apiCall(
endPoint = "langcode",
path = "french",
params = mapOf(Parameter.FORMAT to Format.YAML.value)
)
if (response.statusCode == 200) {
println(response.data)
}
```
```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.