GridProxy API client

June 5, 2023 · View on GitHub

GitHub contributors

Easily access Threefold grid APIs from vlang. gridproxy is v module include the API client along with API-specific information such as the root URL for the different networks available in the threefold grid. They also include classes that represent entities in the context of the API in sub-module model, and that are useful for making conversions between JSON objects and V objects. and some types with helper methods to convert the machine-friendly units returned by the API to more human-friendly units.

GridProxy API client

Getting Started

The project might have multiple branches which can be explained here

main this branch not available yet, it should contains aggregate code of all branches.
development contains code under development. currently it is the default branch.

the project structure is as follows:

vgrid
│  ├─ README.md
├─ LICENSE
├─ README.md
├─ examples
│  ├─ README.md
│  ├─ get_nodes_by_capacity.v
│  └─ get_nodes_by_city_country.v
├─ gridproxy
│  ├─ README.md
│  ├─ docs
│  │  ├─ threefoldtech.vgrid.gridproxy.md
│  │  └─ threefoldtech.vgrid.gridproxy.model.md
│  ├─ gridproxy_core.v
│  ├─ gridproxy_factory.v
│  ├─ gridproxy_highlevel.v
│  ├─ gridproxy_test.v
│  └─ model
│     ├─ contract.v
│     ├─ farm.v
│     ├─ filter.v
│     ├─ iterators.v
│     ├─ model.v
│     ├─ node.v
│     ├─ stats.v
│     └─ twin.v
└─ v.mod

Tools Required

You would require the following tools to develop and run the project:

V language

freeflowuniverse.crystallib v module

v install https://github.com/freeflowuniverse/crystallib

Redis-server unless you are set the caching option to false
- see here for redis-server installation instructions
- start the redis-server on default tcp port, you can use redis-server command.
```
redis-server --daemonize yes
```

or your os specific instructions for running redis-server as a service. on linux/ubuntu you can use

sudo systemctl start redis-server.service

Installation

either clone the repository inside the $HOME/.vmodules/threefoldtech directory

mkdir -p $HOME/.vmodules/threefoldtech
cd $HOME/.vmodules/threefoldtech
git clone https://github.com/threefoldtech/vgrid.git

or use the v install command to install the module.

v install --once -v --git https://github.com/threefoldtech/vgrid

Development

We assume that you runs the commands in the project root directory.

You don't need to worry about formatting your code or setting style guidelines. v fmt takes care of that
```
v fmt -w ./gridproxy/
```
run the tests
```
v -stats test ./gridproxy/ 
```

generate the documentation of gridproxy modules

v doc -m ./gridproxy -f md -o ./gridproxy/docs

client usage

If you want to use the client, you need to import it in your code.

import the client:
```
import threefoldtech.vgrid.gridproxy
```

create a client:

// create a client for the testnet, with API cache disabled
// you can pass true as second arg to enable cache
mut gp_client := gridproxy.get(.test, false)

use the client to interact with the gridproxy API:

// get farm list
farms := gp_client.get_farms()? // you should handle any possible errors in your code
// get gateway list
gateways := gp_client.get_gateways()?
// get node list
nodes := gp_client.get_nodes()?
// get contract list
contracts := gp_client.get_contracts()?
// get grid stats
stats := gp_client.get_stats()?
// get twins
twins := gp_client.get_twins()?

for all available methods on the client, see GridProxy API client modules doc

filtering:

// getting only dedicated farms
farms_dedicated := gp_client.get_farms(dedicated: true)?
// getting only farms with at least one free ip
farms_with_free_ips := gp_client.get_farms(free_ips: u64(1))?
// pagination options:
// get first page of farms
farms_first_page := gp_client.get_farms(page: u64(1))?
// you can mix any filters and pagination options
farms_first_page_dedicated := gp_client.get_farms(page: u64(1), dedicated: true)?
// access the field of first farm in the list
// the API could return an empty list if no farm is found
// you should handle this case in your code
if farms_first_page.len > 0 {
  println(farms_first_page[0].name)
}

for all available filters, see GridProxy API client modules doc

helper methods:

node := nodes[0]
node.updated_at // 1655940222
node.created // 1634637306
// you can convert the timestamp to V Time object easily with the helper method
node.created.to_time() // 2021-10-19 09:55:06
node.created.to_time().local() // 2021-10-19 11:55:06
node.created.to_time().relative() // last Oct 19
node.created.to_time().relative_short() // 246d ago
// lets check another field with different type
node.uptime // 18958736
// you can convert the seconds to a human-readable duration with the helper method
node.uptime.to_days() // 219.42981481481482
node.uptime.to_hours() // 5266.315555555556
node.uptime.to_minutes() // 315978.93333333335
// now to the capacity helper methods
node.total_resources.mru // 202803036160
// you can `to_megabytes`, `to_gigabytes` and `to_terabytes` methods on any resources field.
node.total_resources.mru.to_gigabytes() // 202.80303616
// the helper methods available for the billing to help you convert the TFT units as well

for all available helper methods, see GridProxy API client modules doc

TODO:

Documented the client iterators and higher-level methods

GridProxy API client

Table of Contents

Getting Started

Tools Required

Installation

Development

client usage

Client Examples

Contributing

Versioning

Authors

License

Acknowledgments