Koios API Client Library for Go

Koios API is Elastic Cardano Query Layer!

A consistent query layer for developers to build upon Cardano, with multiple, redundant endpoints that allow for easy scalability.

Repository contains

  1. Koios API Client Library for Go
go get github.com/howijd/koios-rest-go-client

...
import (
  "github.com/howijd/koios-rest-go-client" // imports as package "koios"
)
...
  1. CLI Application to interact with Koios API from Command-line see ./cmd/koios-rest

# provides command `koios-rest` installed into ~/go/bin/koios-rest
go install github.com/howijd/koios-rest-go-client/cmd/[email protected]

PkgGoDev
license

tests
Coverage Status
Go Report Card
GitHub last commit



Install

Using this package requires a working Go environment. See the install instructions for Go.

go get -u github.com/howijd/koios-rest-go-client

Usage

Godoc includes many examples how to use the library see: PkgGoDev
Additionally you can find all usecases by looking source of koio-rest Command-line application source which utilizes entire API of this library.

Basic usage

package main

import (
	"context"
	"fmt"
	"log"

	koios "github.com/howijd/koios-rest-go-client"
)

func main() {
  // Call to koios.New without options is same as calling it with default opts.
  // See godoc for available configuration options.
  // api, err := koios.New(
  // 	koios.Host(koios.MainnetHost),
  // 	koios.APIVersion(koios.DefaultAPIVersion),
  // 	koios.Port(koios.DefaultPort),
  // 	koios.Schema(koios.DefaultSchema),
  // 	koios.HttpClient(koios.DefaultHttpClient),
  // ).
  api, err := koios.New()
  if err != nil {
    log.Fatal(err)
  }

  res, err := api.GetTip(context.Background())
  if err != nil {
	  log.Fatal(err)
  }
  fmt.Println("status: ", res.Status)
  fmt.Println("statu_code: ", res.StatusCode)

  fmt.Println("abs_slot: ", res.Tip[0].AbsSlot)
  fmt.Println("block_no: ", res.Tip[0].BlockNo)
  fmt.Println("block_time: ", res.Tip[0].BlockTime)
  fmt.Println("epoch: ", res.Tip[0].Epoch)
  fmt.Println("epoch_slot: ", res.Tip[0].EpochSlot)
  fmt.Println("hash: ", res.Tip[0].Hash)
}

Concurrency using goroutines

This library is thread-safe so you can freerly use same api client instance passing it to your goroutines.

Following example uses goroutines to query chain tip from different endpoints.

func main() {
  api, _ := koios.New(
    // limit client request 1 per second
    koios.RateLimit(1),
  )
  ctx := context.Background()
  defer cancel()
  var wg sync.WaitGroup
  servers := []string{
    "api.koios.rest",
    "guild.koios.rest",
    "testnet.koios.rest",
  }

  for _, host := range servers {
    wg.Add(1)
    go func(ctx context.Context, host string) {
      defer wg.Done()
      // switching host. all options changes are safe to call 
      // from goroutines.
      koios.Host(host)(api)
      res, _ := api.GET(ctx, "/tip")
      defer res.Body.Close()
      body, _ := ioutil.ReadAll(res.Body)
      fmt.Println(string(body))
    }(ctx, host)
  }
  
  wg.Wait()
  fmt.Println("requests done: ", api.TotalRequests())
}

Implemented Endpoints

WORK IN PROGRESS

endpoint Method koios-rest Cmd Godoc API Doc
NETWORK
/tip *.GetTip(...) *TipResponse tip
/genesis *.GetGenesis(...) *GenesisResponse genesis PkgGoDev
/totals *.GetTotals(...) *TotalsResponse totals PkgGoDev
EPOCH
BLOCK
TRANSACTIONS
ADDRESS
ACCOUNT
POOL
SCRIPT

GitHub

View Github