tallgrass

The tallgrass package is a Gleam wrapper for the PokeAPI and is installable via hex.

gleam add tallgrass

Get started with the examples below. Further documentation can be found at https://hexdocs.pm/tallgrass.

Examples

Fetching resources by name or ID

The majority of PokeAPI resources can be fetched directly by either name or ID. Only a few (characteristic, contest-effect, evolution-chain, machine, and super-contest-effect) need to be fetched by ID.

import tallgrass/client
import tallgrass/machine
import tallgrass/pokemon

fn example() {
  let client = client.new()

  // Pokemon can be fetched by name or ID.
  let assert Ok(ditto) = pokemon.fetch_by_name(client, "ditto")
  let assert Ok(ditto) = pokemon.fetch_by_id(client, 132)

  // Machines can only be fetched by ID.
  let assert Ok(tm_01) = machine.fetch_by_id(client, 2)
}

Paginated resources

You can also fetch (and traverse) paginated resources. The returned resources will only contain the name of the resource (if available) and its corresponding PokeAPI URL.

Pagination options (limit and offset) need to be specified for these requests. Specify one or both of these options using client.PaginationOptions.

import gleam/list
import tallgrass/client.{Limit, Offset, Paginate, with_pagination}
import tallgrass/pokemon

fn example() {
  let client = client.new()

  // default to a limit of 20
  let assert Ok(page) = client |> pokemon.fetch()

  // or specify a different limit or offset, or both
  let assert Ok(page) = client |> with_pagination(Limit(100)) |> pokemon.fetch()
  let assert Ok(page) = client |> with_pagination(Offset(20)) |> pokemon.fetch()
  let assert Ok(page) = client |> with_pagination(Paginate(limit: 100, offset: 20)) |> pokemon.fetch()

  // the returned resources can then be fetched directly
  let assert Ok(resource) = page.results |> list.first
  let assert Ok(pokemon) = pokemon.fetch_resource(client, resource)

  // or you can move on to the next or previous page
  let assert Ok(next_page) = client.next(client, page)
  let assert Ok(previous_page) = client.previous(client, next_page)
}

Caching

Every request response can be cached so that subsequent requests for the same resource can be served without sending an additional HTTP request.

import tallgrass/client.{with_cache}
import tallgrass/client/cache.{Hours}
import tallgrass/pokemon

fn example() {
  // Initialize a new cache with a unique name and the expiration interval.
  let assert Ok(cache) = cache.new("unique-cache-name", Hours(4))
  let client = client.new() |> with_cache(cache)

  let assert Ok(ditto) = pokemon.fetch_by_name(client, "ditto")

  // Subsequent requests will be served from cache/memory instead of the API.
  let assert Ok(ditto) = pokemon.fetch_by_name(client, "ditto")
}