diff --git a/.idea/misc.xml b/.idea/misc.xml index a57f655..84b848d 100644 --- a/.idea/misc.xml +++ b/.idea/misc.xml @@ -1,9 +1,14 @@ + + + + + diff --git a/README.md b/README.md index a45b49c..ad7bac2 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ A simple library to retrieve jokes from [Sv443's JokeAPI](https://v2.jokeapi.dev ## Examples (TL;DR) ```kotlin -import net.thauvin.erik.jokeapi.getJoke +import net.thauvin.erik.jokeapi.joke val joke = joke() val safe = joke(safe = true) @@ -124,8 +124,9 @@ You can also retrieve one or more raw (unprocessed) jokes in all [supported form For example for YAML: ```kotlin -var joke = getRawJokes(format = Format.YAML, idRange = IdRange(22)) -println(joke) +var jokes = getRawJokes(format = Format.YAML, idRange = IdRange(22)) +println(jokes.data) +``` ``` ```yaml error: false @@ -158,7 +159,7 @@ val lang = JokeApi.apiCall( path = "french", params = mapOf(Parameter.FORMAT to Format.YAML.value) ) -println(lang) +println(lang.data) ``` ```yaml error: false diff --git a/src/main/kotlin/net/thauvin/erik/jokeapi/JokeApi.kt b/src/main/kotlin/net/thauvin/erik/jokeapi/JokeApi.kt index 8222435..c33c75b 100644 --- a/src/main/kotlin/net/thauvin/erik/jokeapi/JokeApi.kt +++ b/src/main/kotlin/net/thauvin/erik/jokeapi/JokeApi.kt @@ -54,7 +54,7 @@ object JokeApi { /** * Makes a direct API call. * - * Sse the [JokeAPI Documentation](https://jokeapi.dev/#endpoints) for more details. + * See the [JokeAPI Documentation](https://jokeapi.dev/#endpoints) for more details. */ @JvmStatic @JvmOverloads @@ -64,7 +64,7 @@ object JokeApi { path: String = "", params: Map = emptyMap(), auth: String = "" - ): String { + ): JokeResponse { val urlBuilder = StringBuilder("$API_URL$endPoint") if (path.isNotEmpty()) { @@ -98,7 +98,7 @@ object JokeApi { */ @JvmStatic @Throws(HttpErrorException::class) - fun getRawJokes(config: JokeConfig): String { + fun getRawJokes(config: JokeConfig): JokeResponse { return rawJokes( categories = config.categories, lang = config.lang, @@ -213,7 +213,7 @@ fun joke( idRange = idRange, safe = safe, auth = auth - ) + ).data ) if (json.getBoolean("error")) { throw parseError(json) @@ -281,7 +281,7 @@ fun jokes( amount = amount, safe = safe, auth = auth - ) + ).data ) if (json.getBoolean("error")) { throw parseError(json) @@ -333,6 +333,7 @@ fun jokes( * At the moment, you will only receive one of these tokens temporarily if something breaks or if you are a business * and need more than 120 requests per minute. */ +@Throws(HttpErrorException::class) fun rawJokes( categories: Set = setOf(Category.ANY), lang: Language = Language.EN, @@ -344,7 +345,7 @@ fun rawJokes( amount: Int = 1, safe: Boolean = false, auth: String = "" -): String { +): JokeResponse { val params = mutableMapOf() // Categories diff --git a/src/main/kotlin/net/thauvin/erik/jokeapi/JokeUtil.kt b/src/main/kotlin/net/thauvin/erik/jokeapi/JokeUtil.kt index 2d1f6cb..a6457bb 100644 --- a/src/main/kotlin/net/thauvin/erik/jokeapi/JokeUtil.kt +++ b/src/main/kotlin/net/thauvin/erik/jokeapi/JokeUtil.kt @@ -45,7 +45,7 @@ import java.util.logging.Level /** * Fetch a URL. */ -internal fun fetchUrl(url: String, auth: String = ""): String { +internal fun fetchUrl(url: String, auth: String = ""): JokeResponse { if (JokeApi.logger.isLoggable(Level.FINE)) { JokeApi.logger.fine(url) } @@ -63,11 +63,10 @@ internal fun fetchUrl(url: String, auth: String = ""): String { val body = stream.bufferedReader().use { it.readText() } if (body.isBlank()) { throw httpError(connection.responseCode) - } - if (JokeApi.logger.isLoggable(Level.FINE)) { + } else if (JokeApi.logger.isLoggable(Level.FINE)) { JokeApi.logger.fine(body) } - return body + return JokeResponse(connection.responseCode, body) } finally { connection.disconnect() } diff --git a/src/main/kotlin/net/thauvin/erik/jokeapi/exceptions/HttpErrorException.kt b/src/main/kotlin/net/thauvin/erik/jokeapi/exceptions/HttpErrorException.kt index 947fe04..bcf0173 100644 --- a/src/main/kotlin/net/thauvin/erik/jokeapi/exceptions/HttpErrorException.kt +++ b/src/main/kotlin/net/thauvin/erik/jokeapi/exceptions/HttpErrorException.kt @@ -44,7 +44,6 @@ class HttpErrorException @JvmOverloads constructor( cause: Throwable? = null ) : IOException(message, cause) { companion object { - @Suppress("ConstPropertyName") private const val serialVersionUID = 1L } } diff --git a/src/main/kotlin/net/thauvin/erik/jokeapi/models/JokeResponse.kt b/src/main/kotlin/net/thauvin/erik/jokeapi/models/JokeResponse.kt new file mode 100644 index 0000000..acc129a --- /dev/null +++ b/src/main/kotlin/net/thauvin/erik/jokeapi/models/JokeResponse.kt @@ -0,0 +1,39 @@ +/* + * JokeResponse.kt + * + * Copyright 2022-2024 Erik C. Thauvin (erik@thauvin.net) + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * Redistributions of source code must retain the above copyright notice, this + * list of conditions and the following disclaimer. + * + * Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * Neither the name of this project nor the names of its contributors may be + * used to endorse or promote products derived from this software without + * specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE + * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER + * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, + * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ +package net.thauvin.erik.jokeapi.models + +/** + * The Joke API response. + * + * @property code The HTTP status code. + * @property data The response text. + */ +data class JokeResponse(val code: Int, val data: String) diff --git a/src/main/kotlin/net/thauvin/erik/jokeapi/models/Parameter.kt b/src/main/kotlin/net/thauvin/erik/jokeapi/models/Parameter.kt index 20bdea3..812ca33 100644 --- a/src/main/kotlin/net/thauvin/erik/jokeapi/models/Parameter.kt +++ b/src/main/kotlin/net/thauvin/erik/jokeapi/models/Parameter.kt @@ -34,6 +34,7 @@ package net.thauvin.erik.jokeapi.models /** * The available [URL Parameters](https://jokeapi.dev/#url-parameters). */ +@Suppress("unused") object Parameter { const val AMOUNT = "amount" const val CONTAINS = "contains" diff --git a/src/test/kotlin/net/thauvin/erik/jokeapi/ApiCallTest.kt b/src/test/kotlin/net/thauvin/erik/jokeapi/ApiCallTest.kt index 066f4ca..5c41c7d 100644 --- a/src/test/kotlin/net/thauvin/erik/jokeapi/ApiCallTest.kt +++ b/src/test/kotlin/net/thauvin/erik/jokeapi/ApiCallTest.kt @@ -32,6 +32,7 @@ package net.thauvin.erik.jokeapi import assertk.assertThat +import assertk.assertions.isEqualTo import assertk.assertions.isGreaterThan import assertk.assertions.startsWith import net.thauvin.erik.jokeapi.JokeApi.apiCall @@ -51,8 +52,9 @@ internal class ApiCallTest { fun `Get Flags`() { // See https://v2.jokeapi.dev/#flags-endpoint val response = apiCall(endPoint = "flags") - val json = JSONObject(response) - assertAll("Validate JSON", + val json = JSONObject(response.data) + assertAll( + "Validate JSON", { assertFalse(json.getBoolean("error"), "apiCall(flags).error") }, { assertThat(json.getJSONArray("flags").length(), "apiCall(flags).flags").isGreaterThan(0) }, { assertThat(json.getLong("timestamp"), "apiCall(flags).timestamp").isGreaterThan(0) }) @@ -65,14 +67,16 @@ internal class ApiCallTest { endPoint = "langcode", path = "french", params = mapOf(Parameter.FORMAT to Format.YAML.value) ) - assertContains(lang, "code: \"fr\"", false, "apiCall(langcode, french, yaml)") + assertThat(lang.code).isEqualTo(200) + assertContains(lang.data, "code: \"fr\"", false, "apiCall(langcode, french, yaml)") } @Test fun `Get Ping Response`() { // See https://v2.jokeapi.dev/#ping-endpoint val ping = apiCall(endPoint = "ping", params = mapOf(Parameter.FORMAT to Format.TXT.value)) - assertThat(ping, "apiCall(ping, txt)").startsWith("Pong!") + assertThat(ping.code).isEqualTo(200) + assertThat(ping.data).startsWith("Pong!") } @Test @@ -82,6 +86,7 @@ internal class ApiCallTest { endPoint = "languages", params = mapOf(Parameter.FORMAT to Format.XML.value, Parameter.LANG to Language.FR.value) ) - assertThat(lang).startsWith("") + assertThat(lang.code).isEqualTo(200) + assertThat(lang.data).startsWith("") } } diff --git a/src/test/kotlin/net/thauvin/erik/jokeapi/GetRawJokesTest.kt b/src/test/kotlin/net/thauvin/erik/jokeapi/GetRawJokesTest.kt index cfc7bbe..3a96d1b 100644 --- a/src/test/kotlin/net/thauvin/erik/jokeapi/GetRawJokesTest.kt +++ b/src/test/kotlin/net/thauvin/erik/jokeapi/GetRawJokesTest.kt @@ -34,6 +34,7 @@ package net.thauvin.erik.jokeapi import assertk.all import assertk.assertThat import assertk.assertions.doesNotContain +import assertk.assertions.isEqualTo import assertk.assertions.isNotEmpty import assertk.assertions.startsWith import net.thauvin.erik.jokeapi.models.Format @@ -47,7 +48,8 @@ internal class GetRawJokesTest { @Test fun `Get Raw Joke with TXT`() { val response = rawJokes(format = Format.TXT) - assertThat(response, "rawJoke(txt)").all { + assertThat(response.code).isEqualTo(200) + assertThat(response.data, "rawJoke(data)").all { isNotEmpty() doesNotContain("Error") } @@ -56,24 +58,28 @@ internal class GetRawJokesTest { @Test fun `Get Raw Joke with XML`() { val response = rawJokes(format = Format.XML) - assertThat(response, "rawJoke(xml)").startsWith("\n\n false") + assertThat(response.code).isEqualTo(200) + assertThat(response.data, "rawJoke(xml)").startsWith("\n\n false") } @Test fun `Get Raw Joke with YAML`() { val response = rawJokes(format = Format.YAML) - assertThat(response, "rawJoke(yaml)").startsWith("error: false") + assertThat(response.code).isEqualTo(200) + assertThat(response.data, "rawJoke(yaml)").startsWith("error: false") } @Test fun `Get Raw Jokes`() { val response = rawJokes(amount = 2) - assertContains(response, "\"amount\": 2", false, "rawJoke(2)") + assertThat(response.code).isEqualTo(200) + assertContains(response.data, "\"amount\": 2", false, "rawJoke(2)") } @Test fun `Get Raw Invalid Jokes`() { val response = rawJokes(contains = "foo", safe = true, amount = 2, idRange = IdRange(160, 161)) - assertContains(response, "\"error\": true", false, "getRawJokes(foo)") + assertThat(response.code).isEqualTo(400) + assertContains(response.data, "\"error\": true", false, "getRawJokes(foo)") } } diff --git a/src/test/kotlin/net/thauvin/erik/jokeapi/JokeConfigTest.kt b/src/test/kotlin/net/thauvin/erik/jokeapi/JokeConfigTest.kt index eb01e33..d5c37c3 100644 --- a/src/test/kotlin/net/thauvin/erik/jokeapi/JokeConfigTest.kt +++ b/src/test/kotlin/net/thauvin/erik/jokeapi/JokeConfigTest.kt @@ -102,8 +102,9 @@ internal class JokeConfigTest { amount(2) safe(true) }.build() - val joke = getRawJokes(config) - assertContains(joke, "----------------------------------------------", false, "config.amount(2)") + val jokes = getRawJokes(config) + assertThat(jokes.code).isEqualTo(200) + assertContains(jokes.data, "----------------------------------------------", false, "config.amount(2)") } @Test diff --git a/src/test/kotlin/net/thauvin/erik/jokeapi/JokeUtilTest.kt b/src/test/kotlin/net/thauvin/erik/jokeapi/JokeUtilTest.kt index 56839e8..42e47a0 100644 --- a/src/test/kotlin/net/thauvin/erik/jokeapi/JokeUtilTest.kt +++ b/src/test/kotlin/net/thauvin/erik/jokeapi/JokeUtilTest.kt @@ -33,6 +33,7 @@ package net.thauvin.erik.jokeapi import assertk.assertThat import assertk.assertions.contains +import assertk.assertions.isEqualTo import org.json.JSONException import org.json.JSONObject import org.junit.jupiter.api.Test @@ -54,7 +55,8 @@ internal class JokeUtilTest { @Test fun `Validate Authentication Header`() { val token = "AUTH-TOKEN" - val body = fetchUrl("https://postman-echo.com/get", token) - assertThat(body, "body").contains("\"authentication\": \"$token\"") + val response = fetchUrl("https://postman-echo.com/get", token) + assertThat(response.code).isEqualTo(200) + assertThat(response.data, "body").contains("\"authentication\": \"$token\"") } }