PokeAPI Scala Client

Scala 3 client implementation for the Pokemon API

To get started check the documentation on https://pokeapi.co/docs/v2

Getting Started

Add the following to your build.sbt:

libraryDependencies += "io.github.juliano" % "pokeapi-scala_3" % "0.3.0"

Sttp backends support

This client is written using sttp, so all of the sttp backends published for Scala 3 are supported.

Usage

Instantiate a backend implicitly, create a PokeApiClient() and start consuming the api, calling client.send(PokeRequest(id | name)). Most requests accept an id: Long or name: String (have a look at Scala 3 Union Types).

It's possible to list / paginate resources as well, calling client.send(PokeRequest.resourceList(offset: Int, limit: Int))

Caching

Every response is automatically cached in memory, making all subsequent requests to the same resource pull cached data.

Examples

HttpClient

import io.github.juliano.pokeapi.requests.BerryRequest
import sttp.client3.{ HttpClientSyncBackend, Identity, SttpBackend }

given backend: SttpBackend[Identity, Any] = HttpClientSyncBackend()
val client = PokeApiClient()

val berry = client.send(BerryRequest(1))
println(berry.name)

Try

import io.github.juliano.pokeapi.requests.MoveRequest
import sttp.client3.{ SttpBackend, TryHttpURLConnectionBackend }
import scala.util.*

given backend: SttpBackend[Try, Any] = TryHttpURLConnectionBackend()
val client = PokeApiClient()

client.send(MoveRequest("pound")) match {
    case Success(move) => println(move.names)
    case Failure(t)    => println(s"Failed with: $t")
}

Future

import io.github.juliano.pokeapi.requests.ContestTypeRequest
import sttp.capabilities.WebSockets
import sttp.client3.{ HttpClientFutureBackend, SttpBackend }
import scala.concurrent.ExecutionContext.Implicits.global
import scala.concurrent.Future
import scala.util.*

given backend: SttpBackend[Future, WebSockets] = HttpClientFutureBackend()
val client = PokeApiClient()

client.send(ContestTypeRequest(1)).onComplete {
    case Success(contest) => println(contest.names)
    case Failure(t)       => println(s"Failed with: $t")
}

ZIO

import io.github.juliano.pokeapi.requests.PokemonRequest
import sttp.client3.asynchttpclient.zio.AsyncHttpClientZioBackend
import zio.{ Runtime, Unsafe, ZIO }

val client = AsyncHttpClientZioBackend().map(implicit backend => PokeApiClient())

val zio = client.flatMap(_.send(PokemonRequest("bulbasaur")))
val pokemon = Unsafe.unsafeCompat { implicit u =>
  Runtime.default.unsafe.run(zio).getOrThrowFiberFailure()
}
print(pokemon.id)

Cats Effect

import cats.effect.IO
import cats.effect.unsafe.implicits.global
import io.github.juliano.pokeapi.requests.LocationRequest
import sttp.client3.asynchttpclient.cats.AsyncHttpClientCatsBackend

val client = AsyncHttpClientCatsBackend[IO]().map(implicit backend => PokeApiClient())

val list = client.flatMap(_.send(LocationRequest.resourceList())).unsafeRunSync()
print(list.count)

You can find more examples using Fs2, Armaria and okhttp in the tests

Contributing

Feel free to open pull requests or submit issues!

License

pokeapi-scala is available as open source under the terms of the MIT license.