A Rubyist in Go Land: Your First Pokémon API Client

require "fileutils"
require "net/http"

MIRROR = "https://raw.githubusercontent.com/PokeAPI/api-data/master/data"
FIXTURE_DIR = File.expand_path("fixtures/data/api/v2/pokemon", __dir__)

# api-data stores records by id, so we keep a small name lookup here.
# Add to this map as the series grows.
POKEMON = {
  "bulbasaur"  => 1,
  "charmander" => 4,
  "squirtle"   => 7,
  "pikachu"    => 25
}.freeze

FileUtils.mkdir_p(FIXTURE_DIR)

POKEMON.each do |poke_name, national_id|
  response = Net::HTTP.get_response(URI("#{MIRROR}/api/v2/pokemon/#{national_id}/index.json"))

  unless response.is_a?(Net::HTTPSuccess)
    abort("Mirror returned #{response.code} for #{poke_name}, giving up")
  end

  File.write(File.join(FIXTURE_DIR, poke_name), response.body)
  File.write(File.join(FIXTURE_DIR, national_id.to_s), response.body)

  puts format("fetched %-10s (%6d bytes)", poke_name, response.body.bytesize)
end

// Serves the local PokeAPI fixtures so we never hit the live API.
//
//    go run ./cmd/serve-fixtures
//    curl http://localhost:9595/api/v2/pokemon/bulbasaur
package main

import (
    "log"
    "net/http"
    "os"
)

func main() {
    // Default to the fixtures directory the fetch script creates.
    // Pass a different path as an argument if you cloned api-data.
    fixtureDir := "fixtures/data"
    if len(os.Args) > 1 {
        fixtureDir = os.Args[1]
    }

    // `http.FileServer` serves static files from a directory. It maps
    // the request path directly to the filesystem, so a request for
    // /api/v2/pokemon/bulbasaur looks for fixtures/data/api/v2/pokemon/bulbasaur.
    // No routing needed because we wrote the fixture files without extensions.
    //
    // `http.ListenAndServe` blocks forever (or until it errors).
    // `log.Fatal` prints the error and exits if the server dies.
    address := ":9595"
    log.Printf("Serving %s on http://localhost%s/api/v2", fixtureDir, address)
    log.Fatal(http.ListenAndServe(address, http.FileServer(http.Dir(fixtureDir))))
}

# Fetches one Pokemon and prints its profile. Point POKEAPI_URL at a
# different server to use the live API or another mirror.
#
#   ruby pokemon.rb bulbasaur
#   POKEAPI_URL=https://pokeapi.co/api/v2 ruby pokemon.rb bulbasaur

require "json"
require "net/http"

BASE_URL = ENV.fetch("POKEAPI_URL", "http://localhost:9595/api/v2")

# Yes, I like my Perl-isms
query = ARGV.first or abort("usage: pokemon.rb NAME")

response = Net::HTTP.get_response(URI("#{BASE_URL}/pokemon/#{query.downcase}"))
abort("No Pokémon named #{query.inspect}") unless response.is_a?(Net::HTTPSuccess)

pokemon = JSON.parse(response.body, symbolize_names: true)

pokemon => { id:, name:, types:, abilities:, stats: }

puts "##{id.to_s.rjust(4, '0')} #{name.capitalize}"
puts "Types:     #{types.sort_by { _1[:slot] }.map { _1.dig(:type, :name) }.join(' / ')}"
puts "Abilities: #{abilities.map { _1.dig(:ability, :name) }.join(', ')}"
puts

stats
  .map { [_1.dig(:stat, :name), _1[:base_stat]] }
  .sort_by(&:last)
  .reverse_each do |stat_name, base_stat|
    puts format("%-16s %3d %s", stat_name, base_stat, "█" * (base_stat / 5))
  end

pokemon => { id:, name:, types:, abilities:, stats: }

// In Go you define the shape of your data with structs before you use
// it. There is no equivalent to a loose Hash; every field has a name
// and a type declared up front. The backtick annotations (called
// "struct tags") tell the JSON decoder which key in the JSON maps to
// which field. `json:"name"` means "fill this field from the JSON key
// called name."
//
// In Ruby you'd just parse into a Hash and dig through it. Go makes
// you name everything first, but in return the compiler catches typos
// and wrong types before the code ever runs.

// NamedResource is PokeAPI's NamedAPIResource: a name plus a URL
// pointing at the full record. It appears all over the schema in
// types, abilities, and stats, so we extract it once.
type NamedResource struct {
    Name string `json:"name"`
    URL  string `json:"url"`
}

// Each of these structs maps to one object in the JSON arrays.
// `[]TypeSlot` in the Pokemon struct below means "a slice (dynamic
// array) of TypeSlot values."
type TypeSlot struct {
    Slot int           `json:"slot"`
    Type NamedResource `json:"type"`
}

type AbilitySlot struct {
    Ability  NamedResource `json:"ability"`
    IsHidden bool          `json:"is_hidden"`
}

type StatLine struct {
    BaseStat int           `json:"base_stat"`
    Stat     NamedResource `json:"stat"`
}

// Pokemon is the top-level response from GET /api/v2/pokemon/{name}.
// We only declare the fields we care about; the decoder silently
// ignores any JSON keys that don't have a matching struct field.
type Pokemon struct {
    ID        int           `json:"id"`
    Name      string        `json:"name"`
    Types     []TypeSlot    `json:"types"`
    Abilities []AbilitySlot `json:"abilities"`
    Stats     []StatLine    `json:"stats"`
}

// Go has no built-in `capitalize`, so you write one yourself.
// This only handles ASCII which is fine for Pokémon names.
// In Ruby: `name.capitalize`.
func capitalize(word string) string {
    if word == "" {
        return word
    }
    return strings.ToUpper(word[:1]) + word[1:]
}

func main() {
    // `os.Args` includes the program name at index 0 (unlike Ruby's
    // ARGV which starts at the first real argument).
    if len(os.Args) < 2 {
        fmt.Fprintln(os.Stderr, "usage: pokemon-quick NAME")
        os.Exit(1)
    }

    // `cmp.Or` returns the first non-zero value. For strings the zero
    // value is "", so this works like `ENV.fetch("POKEAPI_URL", default)`.
    baseURL := cmp.Or(os.Getenv("POKEAPI_URL"), "https://pokeapi.co/api/v2")

    // `http.Get` uses Go's default HTTP client, which has NO timeout.
    // If the server hangs, this hangs forever. We fix this later.
    // The `(response, err)` return pair is Go's convention for fallible
    // operations. You must check `err` before touching `response`.
    response, err := http.Get(fmt.Sprintf("%s/pokemon/%s", baseURL, strings.ToLower(os.Args[1])))
    if err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
    // `defer` is Go's `ensure`. It runs when the function exits,
    // regardless of how. We need it because the response body is an
    // open connection that leaks if we forget to close it.
    //
    // The `func() { _ = ... }()` wrapper is because Go's `errcheck`
    // linter complains if you ignore the error from `Close()`. The
    // `_ =` explicitly discards it, which tells the linter "yes I know
    // this returns an error, I'm choosing to ignore it here because
    // there's nothing useful to do with a close error on a read body."
    defer func() { _ = response.Body.Close() }()

    if response.StatusCode != http.StatusOK {
        fmt.Fprintf(os.Stderr, "no Pokémon named %q (%s)\n", os.Args[1], response.Status)
        os.Exit(1)
    }

    // `json.NewDecoder` reads JSON from the response body stream and
    // `Decode(&pokemon)` fills our struct fields using the `json:""`
    // tags we defined above. The `&` passes a pointer so the decoder
    // writes into our variable rather than a copy.
    // In Ruby this whole step is `JSON.parse(body, symbolize_names: true)`.
    var pokemon Pokemon
    if err := json.NewDecoder(response.Body).Decode(&pokemon); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }

// `slices.SortFunc` sorts a slice in-place using a comparison
// function you provide. In Ruby you'd write `sort_by { _1.slot }`
// or use `<=>` in a sort block. Go does not have `<=>` as an
// operator, so the `cmp` package fills that role.
//
// `cmp.Compare(a, b)` takes two ordered values and returns:
//   -1 if a < b
//    0 if a == b
//   +1 if a > b
//
// This is the same contract as Ruby's `<=>`. The function you pass
// to `SortFunc` receives two elements and returns negative (left
// first), zero (equal), or positive (right first).
//
// We sort by `Slot` so the primary type (slot 1) prints before the
// secondary type (slot 2).
slices.SortFunc(pokemon.Types, func(left, right TypeSlot) int {
    return cmp.Compare(left.Slot, right.Slot)
})

// `make([]string, n)` allocates a string slice of length n, all
// empty strings. We fill it by walking the sorted types and pulling
// each name out.
//
// In Ruby this would be:
//   pokemon.types.map { _1.dig(:type, :name) }
//
// Go has no `map` equivalent in the standard library, you write the
// loop. The tradeoff is that you always know exactly what's
// happening and what type you're working with at each step.
typeNames := make([]string, len(pokemon.Types))
for position, slot := range pokemon.Types {
    typeNames[position] = slot.Type.Name
}

// Same pattern for abilities: allocate, loop, extract.
abilityNames := make([]string, len(pokemon.Abilities))
for position, slot := range pokemon.Abilities {
    abilityNames[position] = slot.Ability.Name
}

// `fmt.Printf` works like C's `printf` or Ruby's `format`/`sprintf`.
// `%04d` pads the ID to 4 digits with leading zeros.
// `strings.Join` is the equivalent of `Array#join` in Ruby.
fmt.Printf("#%04d %s\n", pokemon.ID, capitalize(pokemon.Name))
fmt.Printf("Types:     %s\n", strings.Join(typeNames, " / "))
fmt.Printf("Abilities: %s\n\n", strings.Join(abilityNames, ", "))

// Sort stats descending by base value. Note `right.BaseStat` comes
// first in `cmp.Compare`, which reverses the order. In Ruby you'd
// write `sort_by(&:last).reverse_each` or `sort_by { -_1.last }`.
// Go has no reverse sort shorthand, you swap the arguments.
slices.SortFunc(pokemon.Stats, func(left, right StatLine) int {
    return cmp.Compare(right.BaseStat, left.BaseStat)
})

// `%-16s` left-aligns the stat name in a 16-character field.
// `%3d` right-aligns the number in 3 characters.
// `strings.Repeat("█", n)` is the equivalent of `"█" * n` in Ruby.
for _, line := range pokemon.Stats {
    fmt.Printf("%-16s %3d %s\n", line.Stat.Name, line.BaseStat, strings.Repeat("█", line.BaseStat/5))
}

def net_http_defaults
  http = Net::HTTP.new("example.com")

  {
    open_timeout: http.open_timeout,
    read_timeout: http.read_timeout
  }
end

// `Client` is a struct that holds the configuration for talking to
// PokeAPI. In Ruby you might make a class with `initialize` storing
// `@base_url` and `@http`. Go uses structs with fields instead of
// instance variables. Lowercase field names (`baseURL`, `httpClient`)
// are private to this package, like Ruby's `private attr_reader`.
type Client struct {
    baseURL    string
    httpClient *http.Client
}

// `New` is the conventional Go constructor name (there are no special
// constructor methods like `initialize`). It returns a pointer to a
// Client (`*Client`). The `&Client{...}` syntax allocates a Client
// and returns its address.
//
// The key difference from the quick draft: we build our own
// `http.Client` with an explicit 10-second timeout. The default
// client that `http.Get` uses has NO timeout at all, which means a
// hung server will block forever. Ruby's `Net::HTTP` defaults to 60
// seconds for both open and read; Go defaults to infinity.
func New(baseURL string) *Client {
    if baseURL == "" {
        baseURL = DefaultBaseURL
    }

    return &Client{
        baseURL: strings.TrimRight(baseURL, "/"),
        httpClient: &http.Client{
            Timeout: 10 * time.Second,
        },
    }
}

// `Pokemon` is a method on `*Client` (the `(client *Client)` part is
// called a "receiver", Go's version of `self`). It takes a
// `context.Context` and a name, and returns either a `Pokemon` value
// or an error. Go functions can return multiple values; the
// convention for fallible operations is `(result, error)`.
//
// `context.Context` carries deadlines and cancellation signals. When
// the client's 10-second timeout fires, the context is cancelled and
// the request aborts. In Ruby you'd set `Net::HTTP#read_timeout`;
// Go threads the deadline through every layer via context.
func (client *Client) Pokemon(ctx context.Context, name string) (Pokemon, error) {
    requestURL := fmt.Sprintf("%s/pokemon/%s", client.baseURL, strings.ToLower(name))

    // `http.NewRequestWithContext` builds a request and attaches the
    // context to it. This is how the timeout reaches the network call.
    // If the URL is malformed this returns an error immediately.
    request, err := http.NewRequestWithContext(ctx, http.MethodGet, requestURL, nil)
    if err != nil {
        return Pokemon{}, fmt.Errorf("building request for %s: %w", name, err)
    }

    // `client.httpClient.Do(request)` sends the request using our
    // configured client (with the timeout). Unlike `http.Get` which
    // uses the global default client, this respects our deadline.
    response, err := client.httpClient.Do(request)
    if err != nil {
        // `%w` wraps the original error so callers can inspect it with
        // `errors.Is` or `errors.As` later. This is Go's version of
        // exception chaining (like Ruby's `cause`).
        return Pokemon{}, fmt.Errorf("fetching %s: %w", name, err)
    }
    // Explicitly discard the Close error with `_ =` to satisfy the
    // errcheck linter. A close error on a response we already read
    // from has no recovery path, but the linter wants proof you
    // thought about it.
    defer func() { _ = response.Body.Close() }()

    if response.StatusCode != http.StatusOK {
        return Pokemon{}, fmt.Errorf("no Pokémon named %q (%s)", name, response.Status)
    }

    var pokemon Pokemon
    if err := json.NewDecoder(response.Body).Decode(&pokemon); err != nil {
        return Pokemon{}, fmt.Errorf("decoding %s: %w", name, err)
    }

    return pokemon, nil
}

// `main` does one thing: call `run` and translate its error into an
// exit code. This pattern keeps `main` trivial and makes the real
// logic testable (you can call `run` from a test without triggering
// `os.Exit`). In Ruby you'd put everything in the script body; Go
// convention separates "exit policy" from "program logic."
func main() {
    if err := run(os.Args[1:]); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

// `run` returns an error instead of calling `os.Exit` directly.
// Every failure path returns an error with context about what went
// wrong, and `main` decides what to do with it (here: print and exit 1).
// In Ruby you'd `abort` or `raise`; Go makes the error a return value
// you pass back up the call stack.
func run(args []string) error {
    if len(args) < 1 {
        return fmt.Errorf("usage: pokemon NAME")
    }

    // `pokeapi.New` is our client constructor from internal/pokeapi.
    // The `internal/` directory means only code inside this module can
    // import it. Other Go modules cannot reach in, giving us a private
    // API boundary without access modifiers on every method.
    client := pokeapi.New(os.Getenv("POKEAPI_URL"))

    // `context.Background()` is the root context with no deadline of
    // its own. The client's 10-second timeout still applies because
    // `New` configured it on the `http.Client`. In later posts we'll
    // pass contexts with tighter deadlines or cancellation signals.
    pokemon, err := client.Pokemon(context.Background(), args[0])
    if err != nil {
        return err
    }

    printProfile(pokemon)
    return nil
}

pokemon => { id:, name:, types:, abilities:, stats: }