GridProxy API client

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.

import the client:

import freeflowuniverse.crystallib.threefold.gridproxy

// 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 node by id
node := gp_client.get_node_by_id(u64(16))!
// get node stats
node_stats := gp_client.get_node_stats_by_id(u64(16))!
// 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

Client Examples

there are scripts available to serve as examples in the examples directory. Docs

fn contractfilter() !model.ContractFilter

fn farmfilter() !model.FarmFilter

fn new(args GridProxyClientArgs) !&GridProxyClient

get returns a gridproxy client for the given net.

 net TFGridNet = .main
 cache bool

fn nodefilter() !model.NodeFilter

fn statfilter() !model.StatFilter

fn twinfilter() !model.TwinFilter

enum TFGridNet {
	main
	test
	dev
	qa
}

struct GridProxyClient {
pub mut:
	http_client httpconnection.HTTPConnection
}

fn (mut c GridProxyClient) get_contract_bill(contract_id u64) ![]Bill

fn (mut c GridProxyClient) get_contract_hourly_bill(contract_id u64) !f64

fn (mut c GridProxyClient) get_contracts(params ContractFilter) ![]Contract

get_contracts fetchs contracts information with pagination.

• contract_id (u64): Contract id. [optional].

• contract_type (string): [optional].

• deployment_data (string): Contract deployment data in case of 'node' contracts. [optional].

• deployment_hash (string): Contract deployment hash in case of 'node' contracts. [optional].

• name (string): Contract name in case of 'name' contracts. [optional].

• node_id (u64): Node id which contract is deployed on in case of ('rent' or 'node' contracts). [optional].

• number_of_public_ips (u64): Min number of public ips in the 'node' contract. [optional].

• page (u64): Page number. [optional].

• randomize (bool): [optional].

• ret_count (bool): Set farms' count on headers based on filter. [optional].

• size (u64): Max result per page. [optional].

• state (string): Contract state 'Created', or 'Deleted'. [optional].

• twin_id (u64): Twin id. [optional].

• type (string): Contract type 'node', 'name', or 'rent'. [optional].

• returns: []Contract or Error.

fn (mut c GridProxyClient) get_contracts_active(twin_id u64) []Contract

get_active_contracts returns iterator over created contracts owned by specific twin.

• twin_id: twin id.

returns: ContractIterator.

fn (mut c GridProxyClient) get_contracts_by_node_id(node_id u64) []Contract

get_contracts_by_node_id returns iterator over all contracts deployed on specific node.

• node_id: node id.

returns: ContractIterator.

fn (mut c GridProxyClient) get_contracts_by_twin_id(twin_id u64) []Contract

get_contracts_by_twin_id returns iterator over all contracts owned by specific twin.

• twin_id: twin id.

returns: ContractIterator.

fn (mut c GridProxyClient) get_farm_by_id(farm_id u64) !Farm

fetch specific farm information by id.

• farm_id: farm id.

returns: Farm or Error.

fn (mut c GridProxyClient) get_farm_by_name(farm_name string) !Farm

fetch specific farm information by farm name.

• farm_name: farm name.

returns: Farm or Error.

fn (mut c GridProxyClient) get_farms(params FarmFilter) ![]Farm

get_farms fetchs farms information and public ips.

• certification_type (string): Certificate type DIY or Certified. [optional].
• country (string): Farm country. [optional].
• dedicated (bool): Farm is dedicated. [optional].
• farm_id (u64): Farm id. [optional].
• free_ips (u64): Min number of free ips in the farm. [optional].
• name_contains (string): Farm name contains. [optional].
• name (string): Farm name. [optional].
• node_available_for (u64): Twin ID of user for whom there is at least one node that is available to be deployed to in the farm. [optional].
• node_certified (bool): True for farms who have at least one certified node. [optional].
• node_free_hru (u64): Min free reservable hru for at least a single node that belongs to the farm, in bytes. [optional].
• node_free_mru (u64): Min free reservable mru for at least a single node that belongs to the farm, in bytes. [optional].
• node_free_sru (u64): Min free reservable sru for at least a single node that belongs to the farm, in bytes. [optional].
• node_has_gpu (bool): True for farms who have at least one node with a GPU
• node_rented_by (u64): Twin ID of user who has at least one rented node in the farm
• node_status (string): Node status for at least a single node that belongs to the farm
• page (u64): Page number. [optional].
• pricing_policy_id (u64): Pricing policy id. [optional].
• randomize (bool): [optional].
• ret_count (bool): Set farms' count on headers based on filter. [optional].
• size (u64): Max result per page. [optional].
• stellar_address (string): Farm stellar_address. [optional].
• total_ips (u64): Min number of total ips in the farm. [optional].
• twin_id (u64): Twin id associated with the farm. [optional].
• version (u64): Farm version. [optional].

returns: []Farm or Error.

fn (mut c GridProxyClient) get_farms_by_twin_id(twin_id u64) []Farm

get_farms_by_twin_id returns iterator over all farms information associated with specific twin.

• twin_id: twin id.

returns: FarmIterator.

fn (mut c GridProxyClient) get_gateway_by_id(node_id u64) !Node

get_gateway_by_id fetchs specific gateway information by node id.

• node_id (u64): node id.

returns: Node or Error.

fn (mut c GridProxyClient) get_gateways(params NodeFilter) ![]Node

get_gateways fetchs gateways information and public configurations and domains with pagination.

• available_for (u64): Available for twin id. [optional].
• certification_type (string): Certificate type NotCertified, Silver or Gold. [optional].
• city_contains (string): Node partial city filter. [optional].
• city (string): Node city filter. [optional].
• country_contains (string): Node partial country filter. [optional].
• country (string): Node country filter. [optional].
• dedicated (bool): Set to true to get the dedicated nodes only. [optional].
• domain (bool): Set to true to filter nodes with domain. [optional].
• farm_ids ([]u64): List of farm ids. [optional].
• farm_name_contains (string): Get nodes for specific farm. [optional].
• farm_name (string): Get nodes for specific farm. [optional].
• free_hru (u64): Min free reservable hru in bytes. [optional].
• free_ips (u64): Min number of free ips in the farm of the node. [optional].
• free_mru (u64): Min free reservable mru in bytes. [optional].
• free_sru (u64): Min free reservable sru in bytes. [optional].
• gpu_available (bool): Filter nodes that have available GPU. [optional].
• gpu_device_id (string): Filter nodes based on GPU device ID. [optional].
• gpu_device_name (string): Filter nodes based on GPU device partial name. [optional].
• gpu_vendor_id (string): Filter nodes based on GPU vendor ID. [optional].
• gpu_vendor_name (string): Filter nodes based on GPU vendor partial name. [optional].
• has_gpu: Filter nodes on whether they have GPU support or not. [optional].
• ipv4 (string): Set to true to filter nodes with ipv4. [optional].
• ipv6 (string): Set to true to filter nodes with ipv6. [optional].
• node_id (u64): Node id. [optional].
• page (u64): Page number. [optional].
• rentable (bool): Set to true to filter the available nodes for renting. [optional].
• rented_by (u64): Rented by twin id. [optional].
• ret_count (bool): Set nodes' count on headers based on filter. [optional].
• size (u64): Max result per page. [optional].
• status (string): Node status filter, set to 'up' to get online nodes only. [optional].
• total_cru (u64): Min total cru in bytes. [optional].
• total_hru (u64): Min total hru in bytes. [optional].
• total_mru (u64): Min total mru in bytes. [optional].
• total_sru (u64): Min total sru in bytes. [optional].
• twin_id (u64): Twin id. [optional].

returns: []Node or Error.

fn (mut c GridProxyClient) get_node_by_id(node_id u64) !Node

get_node_by_id fetchs specific node information by node id.

• node_id (u64): node id.

returns: Node or Error.

fn (mut c GridProxyClient) get_node_stats_by_id(node_id u64) !NodeStats

get_node_stats_by_id fetchs specific node statistics by node id.

• node_id (u64): node id.

returns: Node_stats or Error.

fn (mut c GridProxyClient) get_nodes(params NodeFilter) ![]Node

get_nodes fetchs nodes information and public configurations with pagination.

• available_for (u64): Available for twin id. [optional].
• certification_type (string): Certificate type NotCertified, Silver or Gold. [optional].
• city_contains (string): Node partial city filter. [optional].
• city (string): Node city filter. [optional].
• country_contains (string): Node partial country filter. [optional].
• country (string): Node country filter. [optional].
• dedicated (bool): Set to true to get the dedicated nodes only. [optional].
• domain (string): Set to true to filter nodes with domain. [optional].
• farm_ids ([]u64): List of farm ids. [optional].
• farm_name_contains (string): Get nodes for specific farm. [optional].
• farm_name (string): Get nodes for specific farm. [optional].
• free_hru (u64): Min free reservable hru in bytes. [optional].
• free_ips (u64): Min number of free ips in the farm of the node. [optional].
• free_mru (u64): Min free reservable mru in bytes. [optional].
• free_sru (u64): Min free reservable sru in bytes. [optional].
• gpu_available (bool): Filter nodes that have available GPU. [optional].
• gpu_device_id (string): Filter nodes based on GPU device ID. [optional].
• gpu_device_name (string): Filter nodes based on GPU device partial name. [optional].
• gpu_vendor_id (string): Filter nodes based on GPU vendor ID. [optional].
• gpu_vendor_name (string): Filter nodes based on GPU vendor partial name. [optional].
• has_gpu: Filter nodes on whether they have GPU support or not. [optional].
• ipv4 (string): Set to true to filter nodes with ipv4. [optional].
• ipv6 (string): Set to true to filter nodes with ipv6. [optional].
• node_id (u64): Node id. [optional].
• page (u64): Page number. [optional].
• rentable (bool): Set to true to filter the available nodes for renting. [optional].
• rented_by (u64): Rented by twin id. [optional].
• ret_count (bool): Set nodes' count on headers based on filter. [optional].
• size (u64): Max result per page. [optional].
• status (string): Node status filter, set to 'up' to get online nodes only. [optional].
• total_cru (u64): Min total cru in bytes. [optional].
• total_hru (u64): Min total hru in bytes. [optional].
• total_mru (u64): Min total mru in bytes. [optional].
• total_sru (u64): Min total sru in bytes. [optional].
• twin_id (u64): Twin id. [optional].

returns: []Node or Error.

fn (mut c GridProxyClient) get_stats(filter StatFilter) !GridStat

get_stats fetchs stats about the grid.

• status (string): Node status filter, set to 'up' to get online nodes only.. [optional].

returns: GridStat or Error.

fn (mut c GridProxyClient) get_twin_by_account(account_id string) !Twin

fetch specific twin information by account.

• account_id: account id.

returns: Twin or Error.

fn (mut c GridProxyClient) get_twin_by_id(twin_id u64) !Twin

fetch specific twin information by twin id.

• twin_id: twin id.

returns: Twin or Error.

fn (mut c GridProxyClient) get_twins(params TwinFilter) ![]Twin

get_twins fetchs twins information with pagaination.

• account_id (string): Account address. [optional].
• page (u64): Page number. [optional].
• public_key (string): twin public key used for e2e encryption. [optional].
• relay (string): relay domain name. [optional].
• ret_count (bool): Set farms' count on headers based on filter. [optional].
• size (u64): Max result per page. [optional].
• twin_id (u64): Twin id. [optional].

returns: []Twin or Error.

fn (mut c GridProxyClient) is_pingable() !bool

is_pingable checks if API server is reachable and responding.

returns: bool, true if API server is reachable and responding, false otherwise

struct GridProxyClientArgs {
pub mut:
	net   TFGridNet = .main
	cache bool
}