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 = joke()
val safe = joke(safe = true)
val pun = joke(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 = jokes(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.joke(config);
joke.getJoke().forEach(System.out::println);

bld

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

repositories = List.of(MAVEN_CENTRAL);

scope(compile)
    .include(dependency("net.thauvin.erik:jokeapi:0.9.1"));

Be sure to use the bld Kotlin extension in your project.

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.1")
}

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

Contributing

If you want to contribute to this project, all you have to do is clone the GitHub repository:

git clone git@github.com:ethauvin/jokeapi.git

Then use bld to build:

cd jokeapi
./bld compile

The project has an IntelliJ IDEA project structure. You can just open it after all the dependencies were downloaded and peruse the code.