JokeAPI for Kotlin, Java and Android

A simple library to retrieve jokes from Sv443's JokeAPI.

Examples (TL;DR)

import net.thauvin.erik.jokeapi.getJoke

val joke = getJoke()
val safe = getJoke(safe = true)
val pun = getJoke(categories = setOf(Category.PUN))

The parameters match the joke endpoint.

A Joke class instance is returned, matching the response:

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...

To retrieve multiple jokes:

val frenchJokes = getJokes(amount = 2, type = Type.TWOPART, lang = Language.FR)
frenchJokes.forEach {
    println(it.joke.joinToString("\n"))
    println("-".repeat(46))
}

• View more examples...

If an error occurs, a JokeException is thrown, matching the JokeAPI errors:

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:

class HttpErrorException(
    val statusCode: Int,
    message: String,
    cause: Throwable? = null
) : IOException(message, cause)

• View more examples...

Java

To make it easier to use the library with Java, a configuration builder is available:

var config = new JokeConfig.Builder()
        .type(Type.SINGLE)
        .safe(true)
        .build();
var joke = JokeApi.getJoke(config);
joke.getJoke().forEach(System.out::println);

Gradle, Maven, etc.

To use with Gradle, include the following dependency in your build file:

repositories {
    mavenCentral()
    maven { url = uri("https://oss.sonatype.org/content/repositories/snapshots") } // only needed for SNAPSHOT
}

dependencies {
    implementation("net.thauvin.erik:jokeapi:0.9-SNAPSHOT")
}

Instructions for using with Maven, Ivy, etc. can be found on Maven Central.

Raw Jokes

You can also retrieve one or more raw (unprocessed) jokes in all supported formats.

For example for YAML:

var joke = getRawJokes(format = Format.YAML, idRange = IdRange(22))
println(joke)

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...

Extending

A generic apiCall() function is available to access other JokeAPI endpoints.

For example to retrieve the French language code:

val lang = JokeApi.apiCall(
    endPoint = "langcode",
    path = "french",
    params = mapOf(Parameter.FORMAT to Format.YAML.value)
)
println(lang)

error: false
code: "fr"

• View more examples...