api

package
v1.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 19, 2017 License: MIT Imports: 21 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func HttpGET added in v1.0.0

func HttpGET(url string) (resp *http.Response, err error)

HttpGET is a utility function for making http get requests to sia with a whitelisted user-agent. A non-2xx response does not return an error.

func HttpGETAuthenticated added in v1.0.0

func HttpGETAuthenticated(url string, password string) (resp *http.Response, err error)

HttpGETAuthenticated is a utility function for making authenticated http get requests to sia with a whitelisted user-agent and the supplied password. A non-2xx response does not return an error.

func HttpPOST added in v1.0.0

func HttpPOST(url string, data string) (resp *http.Response, err error)

HttpPOST is a utility function for making post requests to sia with a whitelisted user-agent. A non-2xx response does not return an error.

func HttpPOSTAuthenticated added in v1.0.0

func HttpPOSTAuthenticated(url string, data string, password string) (resp *http.Response, err error)

HttpPOSTAuthenticated is a utility function for making authenticated http post requests to sia with a whitelisted user-agent and the supplied password. A non-2xx response does not return an error.

func RequirePassword added in v1.0.3

func RequirePassword(h httprouter.Handle, password string) httprouter.Handle

RequirePassword is middleware that requires a request to authenticate with a password using HTTP basic auth. Usernames are ignored. Empty passwords indicate no authentication is required.

func RequireUserAgent added in v1.0.3

func RequireUserAgent(h http.Handler, ua string) http.Handler

RequireUserAgent is middleware that requires all requests to set a UserAgent that contains the specified string.

func UnrecognizedCallHandler added in v1.0.3

func UnrecognizedCallHandler(w http.ResponseWriter, req *http.Request)

UnrecognizedCallHandler handles calls to unknown pages (404).

func WriteError added in v1.0.3

func WriteError(w http.ResponseWriter, err Error, code int)

WriteError an error to the API caller.

func WriteJSON added in v1.0.3

func WriteJSON(w http.ResponseWriter, obj interface{})

WriteJSON writes the object to the ResponseWriter. If the encoding fails, an error is written instead. The Content-Type of the response header is set accordingly.

func WriteSuccess added in v1.0.3

func WriteSuccess(w http.ResponseWriter)

WriteSuccess writes the HTTP header with status 204 No Content to the ResponseWriter. WriteSuccess should only be used to indicate that the requested action succeeded AND there is no data to return.

Types

type API added in v1.0.3

type API struct {
	// contains filtered or unexported fields
}

API encapsulates a collection of modules and implements a http.Handler to access their methods.

func New added in v1.0.3

func New(requiredUserAgent string, requiredPassword string, cs modules.ConsensusSet, e modules.Explorer, g modules.Gateway, h modules.Host, m modules.Miner, r modules.Renter, tp modules.TransactionPool, w modules.Wallet) *API

New creates a new Sia API from the provided modules. The API will require authentication using HTTP basic auth for certain endpoints of the supplied password is not the empty string. Usernames are ignored for authentication.

func (*API) ServeHTTP added in v1.0.3

func (api *API) ServeHTTP(w http.ResponseWriter, r *http.Request)

api.ServeHTTP implements the http.Handler interface.

type Client added in v1.0.3

type Client struct {
	// contains filtered or unexported fields
}

Client holds fields to make requests to a Sia API.

func NewClient added in v1.0.3

func NewClient(address string, password string) *Client

NewClient creates a new api.Client using the provided address and password. If password is not the empty string, HTTP basic authentication will be used to communicate with the API.

func (*Client) Get added in v1.0.3

func (c *Client) Get(resource string, obj interface{}) error

Get requests the resource at `resource` and decodes it into `obj`, returning an error if requesting or decoding the resource fails. A non-2xx status code constitutes a request failure.

func (*Client) Post added in v1.0.3

func (c *Client) Post(resource string, data string, obj interface{}) error

Post makes a POST request to the resource at `resource`, using `data` as the request body. The response, if provided, will be decoded into `obj`.

type ConsensusGET added in v1.0.0

type ConsensusGET struct {
	Synced       bool              `json:"synced"`
	Height       types.BlockHeight `json:"height"`
	CurrentBlock types.BlockID     `json:"currentblock"`
	Target       types.Target      `json:"target"`
	Difficulty   types.Currency    `json:"difficulty"`
}

ConsensusGET contains general information about the consensus set, with tags to support idiomatic json encodings.

type DownloadInfo

type DownloadInfo struct {
	SiaPath     string    `json:"siapath"`
	Destination string    `json:"destination"`
	Filesize    uint64    `json:"filesize"`
	Received    uint64    `json:"received"`
	StartTime   time.Time `json:"starttime"`
	Error       string    `json:"error"`
}

DownloadInfo contains all client-facing information of a file.

type Error added in v1.0.0

type Error struct {
	// Message describes the error in English. Typically it is set to
	// `err.Error()`. This field is required.
	Message string `json:"message"`
}

Error is a type that is encoded as JSON and returned in an API response in the event of an error. Only the Message field is required. More fields may be added to this struct in the future for better error reporting.

func (Error) Error added in v1.0.0

func (err Error) Error() string

Error implements the error interface for the Error type. It returns only the Message field.

type ExplorerBlock added in v1.0.0

type ExplorerBlock struct {
	MinerPayoutIDs []types.SiacoinOutputID `json:"minerpayoutids"`
	Transactions   []ExplorerTransaction   `json:"transactions"`
	RawBlock       types.Block             `json:"rawblock"`

	modules.BlockFacts
}

ExplorerBlock is a block with some extra information such as the id and height. This information is provided for programs that may not be complex enough to compute the ID on their own.

type ExplorerBlockGET added in v1.0.0

type ExplorerBlockGET struct {
	Block ExplorerBlock `json:"block"`
}

ExplorerBlockGET is the object returned by a GET request to /explorer/block.

type ExplorerGET added in v1.0.0

type ExplorerGET struct {
	modules.BlockFacts
}

ExplorerGET is the object returned as a response to a GET request to /explorer.

type ExplorerHashGET added in v1.0.0

type ExplorerHashGET struct {
	HashType     string                `json:"hashtype"`
	Block        ExplorerBlock         `json:"block"`
	Blocks       []ExplorerBlock       `json:"blocks"`
	Transaction  ExplorerTransaction   `json:"transaction"`
	Transactions []ExplorerTransaction `json:"transactions"`
}

ExplorerHashGET is the object returned as a response to a GET request to /explorer/hash. The HashType will indicate whether the hash corresponds to a block id, a transaction id, a siacoin output id, a file contract id, or a siafund output id. In the case of a block id, 'Block' will be filled out and all the rest of the fields will be blank. In the case of a transaction id, 'Transaction' will be filled out and all the rest of the fields will be blank. For everything else, 'Transactions' and 'Blocks' will/may be filled out and everything else will be blank.

type ExplorerTransaction added in v1.0.0

type ExplorerTransaction struct {
	ID             types.TransactionID `json:"id"`
	Height         types.BlockHeight   `json:"height"`
	Parent         types.BlockID       `json:"parent"`
	RawTransaction types.Transaction   `json:"rawtransaction"`

	SiacoinInputOutputs                      []types.SiacoinOutput     `json:"siacoininputoutputs"` // the outputs being spent
	SiacoinOutputIDs                         []types.SiacoinOutputID   `json:"siacoinoutputids"`
	FileContractIDs                          []types.FileContractID    `json:"filecontractids"`
	FileContractValidProofOutputIDs          [][]types.SiacoinOutputID `json:"filecontractvalidproofoutputids"`          // outer array is per-contract
	FileContractMissedProofOutputIDs         [][]types.SiacoinOutputID `json:"filecontractmissedproofoutputids"`         // outer array is per-contract
	FileContractRevisionValidProofOutputIDs  [][]types.SiacoinOutputID `json:"filecontractrevisionvalidproofoutputids"`  // outer array is per-revision
	FileContractRevisionMissedProofOutputIDs [][]types.SiacoinOutputID `json:"filecontractrevisionmissedproofoutputids"` // outer array is per-revision
	StorageProofOutputIDs                    [][]types.SiacoinOutputID `json:"storageproofoutputids"`                    // outer array is per-payout
	StorageProofOutputs                      [][]types.SiacoinOutput   `json:"storageproofoutputs"`                      // outer array is per-payout
	SiafundInputOutputs                      []types.SiafundOutput     `json:"siafundinputoutputs"`                      // the outputs being spent
	SiafundOutputIDs                         []types.SiafundOutputID   `json:"siafundoutputids"`
	SiafundClaimOutputIDs                    []types.SiacoinOutputID   `json:"siafundclaimoutputids"`
}

ExplorerTransaction is a transcation with some extra information such as the parent block. This information is provided for programs that may not be complex enough to compute the extra information on their own.

type ExtendedHostDBEntry added in v1.1.1

type ExtendedHostDBEntry struct {
	modules.HostDBEntry
	PublicKeyString string `json:"publickeystring"`
}

ExtendedHostDBEntry is an extension to modules.HostDBEntry that includes the string representation of the public key, otherwise presented as two fields, a string and a base64 encoded byte slice.

type GatewayGET added in v1.0.1

type GatewayGET struct {
	NetAddress modules.NetAddress `json:"netaddress"`
	Peers      []modules.Peer     `json:"peers"`
}

GatewayGET contains the fields returned by a GET call to "/gateway".

type HostEstimateScoreGET added in v1.3.0

type HostEstimateScoreGET struct {
	EstimatedScore types.Currency `json:"estimatedscore"`
	ConversionRate float64        `json:"conversionrate"`
}

HostEstimateScoreGET contains the information that is returned from a /host/estimatescore call.

type HostGET added in v1.0.0

type HostGET struct {
	ExternalSettings     modules.HostExternalSettings     `json:"externalsettings"`
	FinancialMetrics     modules.HostFinancialMetrics     `json:"financialmetrics"`
	InternalSettings     modules.HostInternalSettings     `json:"internalsettings"`
	NetworkMetrics       modules.HostNetworkMetrics       `json:"networkmetrics"`
	ConnectabilityStatus modules.HostConnectabilityStatus `json:"connectabilitystatus"`
	WorkingStatus        modules.HostWorkingStatus        `json:"workingstatus"`
}

HostGET contains the information that is returned after a GET request to /host - a bunch of information about the status of the host.

type HostdbActiveGET added in v1.1.1

type HostdbActiveGET struct {
	Hosts []ExtendedHostDBEntry `json:"hosts"`
}

HostdbActiveGET lists active hosts on the network.

type HostdbAllGET added in v1.1.1

type HostdbAllGET struct {
	Hosts []ExtendedHostDBEntry `json:"hosts"`
}

HostdbAllGET lists all hosts that the renter is aware of.

type HostdbHostsGET added in v1.1.1

type HostdbHostsGET struct {
	Entry          ExtendedHostDBEntry        `json:"entry"`
	ScoreBreakdown modules.HostScoreBreakdown `json:"scorebreakdown"`
}

HostdbHostsGET lists detailed statistics for a particular host, selected by pubkey.

type MinerGET added in v1.0.0

type MinerGET struct {
	BlocksMined      int  `json:"blocksmined"`
	CPUHashrate      int  `json:"cpuhashrate"`
	CPUMining        bool `json:"cpumining"`
	StaleBlocksMined int  `json:"staleblocksmined"`
}

MinerGET contains the information that is returned after a GET request to /miner.

type RenterContract added in v1.0.0

type RenterContract struct {
	// Amount of contract funds that have been spent on downloads.
	DownloadSpending types.Currency `json:"downloadspending"`
	// Block height that the file contract ends on.
	EndHeight types.BlockHeight `json:"endheight"`
	// Fees paid in order to form the file contract.
	Fees types.Currency `json:"fees"`
	// Public key of the host the contract was formed with.
	HostPublicKey types.SiaPublicKey `json:"hostpublickey"`
	// ID of the file contract.
	ID types.FileContractID `json:"id"`
	// A signed transaction containing the most recent contract revision.
	LastTransaction types.Transaction `json:"lasttransaction"`
	// Address of the host the file contract was formed with.
	NetAddress modules.NetAddress `json:"netaddress"`
	// Remaining funds left for the renter to spend on uploads & downloads.
	RenterFunds types.Currency `json:"renterfunds"`
	// Size of the file contract, which is typically equal to the number of
	// bytes that have been uploaded to the host.
	Size uint64 `json:"size"`
	// Block height that the file contract began on.
	StartHeight types.BlockHeight `json:"startheight"`
	// Amount of contract funds that have been spent on storage.
	StorageSpending types.Currency `json:"StorageSpending"`
	// Total cost to the wallet of forming the file contract.
	TotalCost types.Currency `json:"totalcost"`
	// Amount of contract funds that have been spent on uploads.
	UploadSpending types.Currency `json:"uploadspending"`
}

RenterContract represents a contract formed by the renter.

type RenterContracts added in v1.0.0

type RenterContracts struct {
	Contracts []RenterContract `json:"contracts"`
}

RenterContracts contains the renter's contracts.

type RenterDownloadQueue added in v1.0.0

type RenterDownloadQueue struct {
	Downloads []DownloadInfo `json:"downloads"`
}

DownloadQueue contains the renter's download queue.

type RenterFiles added in v1.0.0

type RenterFiles struct {
	Files []modules.FileInfo `json:"files"`
}

RenterFiles lists the files known to the renter.

type RenterGET added in v1.0.0

type RenterGET struct {
	Settings         modules.RenterSettings     `json:"settings"`
	FinancialMetrics modules.ContractorSpending `json:"financialmetrics"`
	CurrentPeriod    types.BlockHeight          `json:"currentperiod"`
}

RenterGET contains various renter metrics.

type RenterLoad added in v1.0.0

type RenterLoad struct {
	FilesAdded []string `json:"filesadded"`
}

RenterLoad lists files that were loaded into the renter.

type RenterPricesGET added in v1.1.1

type RenterPricesGET struct {
	modules.RenterPriceEstimation
}

RenterPricesGET lists the data that is returned when a GET call is made to /renter/prices.

type RenterShareASCII added in v1.0.0

type RenterShareASCII struct {
	ASCIIsia string `json:"asciisia"`
}

RenterShareASCII contains an ASCII-encoded .sia file.

type StorageGET added in v1.0.0

type StorageGET struct {
	Folders []modules.StorageFolderMetadata `json:"folders"`
}

StorageGET contains the information that is returned after a GET request to /host/storage - a bunch of information about the status of storage management on the host.

type TpoolFeeGET added in v1.3.0

type TpoolFeeGET struct {
	Minimum types.Currency `json:"minimum"`
	Maximum types.Currency `json:"maximum"`
}

type TpoolRawGET added in v1.3.0

type TpoolRawGET struct {
	ID          types.TransactionID `json:"id"`
	Parents     []byte              `json:"parents"`
	Transaction []byte              `json:"transaction"`
}

TpoolRawGET contains the requested transaction encoded to the raw format, along with the id of that transaction.

type WalletAddressGET added in v1.0.0

type WalletAddressGET struct {
	Address types.UnlockHash `json:"address"`
}

WalletAddressGET contains an address returned by a GET call to /wallet/address.

type WalletAddressesGET added in v1.0.0

type WalletAddressesGET struct {
	Addresses []types.UnlockHash `json:"addresses"`
}

WalletAddressesGET contains the list of wallet addresses returned by a GET call to /wallet/addresses.

type WalletGET added in v1.0.0

type WalletGET struct {
	Encrypted  bool `json:"encrypted"`
	Unlocked   bool `json:"unlocked"`
	Rescanning bool `json:"rescanning"`

	ConfirmedSiacoinBalance     types.Currency `json:"confirmedsiacoinbalance"`
	UnconfirmedOutgoingSiacoins types.Currency `json:"unconfirmedoutgoingsiacoins"`
	UnconfirmedIncomingSiacoins types.Currency `json:"unconfirmedincomingsiacoins"`

	SiafundBalance      types.Currency `json:"siafundbalance"`
	SiacoinClaimBalance types.Currency `json:"siacoinclaimbalance"`

	DustThreshold types.Currency `json:"dustthreshold"`
}

WalletGET contains general information about the wallet.

type WalletInitPOST added in v1.0.0

type WalletInitPOST struct {
	PrimarySeed string `json:"primaryseed"`
}

WalletInitPOST contains the primary seed that gets generated during a POST call to /wallet/init.

type WalletSeedsGET added in v1.0.0

type WalletSeedsGET struct {
	PrimarySeed        string   `json:"primaryseed"`
	AddressesRemaining int      `json:"addressesremaining"`
	AllSeeds           []string `json:"allseeds"`
}

WalletSeedsGET contains the seeds used by the wallet.

type WalletSiacoinsPOST added in v1.0.0

type WalletSiacoinsPOST struct {
	TransactionIDs []types.TransactionID `json:"transactionids"`
}

WalletSiacoinsPOST contains the transaction sent in the POST call to /wallet/siacoins.

type WalletSiafundsPOST added in v1.0.0

type WalletSiafundsPOST struct {
	TransactionIDs []types.TransactionID `json:"transactionids"`
}

WalletSiafundsPOST contains the transaction sent in the POST call to /wallet/siafunds.

type WalletSweepPOST added in v1.2.0

type WalletSweepPOST struct {
	Coins types.Currency `json:"coins"`
	Funds types.Currency `json:"funds"`
}

WalletSweepPOST contains the coins and funds returned by a call to /wallet/sweep.

type WalletTransactionGETid added in v1.0.0

type WalletTransactionGETid struct {
	Transaction modules.ProcessedTransaction `json:"transaction"`
}

WalletTransactionGETid contains the transaction returned by a call to /wallet/transaction/:id

type WalletTransactionsGET added in v1.0.0

type WalletTransactionsGET struct {
	ConfirmedTransactions   []modules.ProcessedTransaction `json:"confirmedtransactions"`
	UnconfirmedTransactions []modules.ProcessedTransaction `json:"unconfirmedtransactions"`
}

WalletTransactionsGET contains the specified set of confirmed and unconfirmed transactions.

type WalletTransactionsGETaddr added in v1.0.0

type WalletTransactionsGETaddr struct {
	ConfirmedTransactions   []modules.ProcessedTransaction `json:"confirmedtransactions"`
	UnconfirmedTransactions []modules.ProcessedTransaction `json:"unconfirmedtransactions"`
}

WalletTransactionsGETaddr contains the set of wallet transactions relevant to the input address provided in the call to /wallet/transaction/:addr

type WalletVerifyAddressGET added in v1.2.2

type WalletVerifyAddressGET struct {
	Valid bool `json:"valid"`
}

WalletVerifyAddressGET contains a bool indicating if the address passed to /wallet/verify/address/:addr is a valid address.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL