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
- 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"
)
...
- 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]
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:
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