api

Documentation

Index

• func HttpGET(url string) (resp *http.Response, err error)
• func HttpGETAuthenticated(url string, password string) (resp *http.Response, err error)
• func HttpPOST(url string, data string) (resp *http.Response, err error)
• func HttpPOSTAuthenticated(url string, data string, password string) (resp *http.Response, err error)
• func RequirePassword(h httprouter.Handle, password string) httprouter.Handle
• func RequireUserAgent(h http.Handler, ua string) http.Handler
• func UnrecognizedCallHandler(w http.ResponseWriter, req *http.Request)
• func WriteError(w http.ResponseWriter, err Error, code int)
• func WriteJSON(w http.ResponseWriter, obj interface{})
• func WriteSuccess(w http.ResponseWriter)
• type API
  • func New(requiredUserAgent string, requiredPassword string, cs modules.ConsensusSet, ...) *API
  • func (api *API) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Client
  • func NewClient(address string, password string) *Client
  • func (c *Client) Get(resource string, obj interface{}) error
  • func (c *Client) Post(resource string, data string, obj interface{}) error
• type ConsensusGET
• type Error
  • func (err Error) Error() string
• type ExplorerBlock
• type ExplorerBlockGET
• type ExplorerGET
• type ExplorerHashGET
• type ExplorerTransaction
• type GatewayGET
• type TransactionPoolGET
• type WalletAddressGET
• type WalletAddressesGET
• type WalletBlockStakeStatsGET
• type WalletBlockStakesPOST
• type WalletCoinsPOST
• type WalletGET
• type WalletInitPOST
• type WalletSeedsGET
• type WalletTransactionGETid
• type WalletTransactionsGET
• type WalletTransactionsGETaddr

Functions

func HttpGET

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

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

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

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

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

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

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

UnrecognizedCallHandler handles calls to unknown pages (404).

func WriteError

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

WriteError an error to the API caller.

func WriteJSON

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

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

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

func New(requiredUserAgent string, requiredPassword string, cs modules.ConsensusSet, e modules.Explorer, g modules.Gateway, 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

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

api.ServeHTTP implements the http.Handler interface.

type Client

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

Client holds fields to make requests to a Sia API.

func NewClient

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

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

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

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

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

type Error

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

func (err Error) Error() string

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

type ExplorerBlock

type ExplorerBlock struct {
	MinerPayoutIDs []types.CoinOutputID  `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

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

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

type ExplorerGET

type ExplorerGET struct {
	modules.BlockFacts
}

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

type ExplorerHashGET

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

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

	CoinInputOutputs       []types.CoinOutput         `json:"coininputoutputs"` // the outputs being spent
	CoinOutputIDs          []types.CoinOutputID       `json:"coinoutputids"`
	BlockStakeInputOutputs []types.BlockStakeOutput   `json:"blockstakeinputoutputs"` // the outputs being spent
	BlockStakeOutputIDs    []types.BlockStakeOutputID `json:"blockstakeoutputids"`
}

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 GatewayGET

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 TransactionPoolGET

type TransactionPoolGET struct {
	Transactions []types.Transaction `json:"transactions"`
}

type WalletAddressGET

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

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

type WalletAddressesGET

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

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

type WalletBlockStakeStatsGET

type WalletBlockStakeStatsGET struct {
	TotalActiveBlockStake types.Currency             `json:"totalactiveblockstake"`
	TotalBlockStake       types.Currency             `json:"totalblockstake"`
	TotalFeeLast1000      types.Currency             `json:"totalfeelast1000"`
	TotalBCLast1000       uint64                     `json:"totalbclast1000"`
	BlockCount            uint64                     `json:"blockcount"`
	TotalBCLast1000t      uint64                     `json:"totalbclast1000t"`
	BlockStakeState       []uint64                   `json:"blockstakestate"`
	BlockStakeNumOf       []types.Currency           `json:"blockstakenumof"`
	BlockStakeUTXOAddress []types.BlockStakeOutputID `json:"blockstakeutxoaddress"`
}

WalletBlockStakeStatsGET contains blockstake statistical info of the wallet.

type WalletBlockStakesPOST

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

WalletBlockStakesPOST contains the transaction sent in the POST call to /wallet/blockstakes.

type WalletCoinsPOST

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

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

type WalletGET

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

	ConfirmedCoinBalance     types.Currency `json:"confirmedcoinbalance"`
	UnconfirmedOutgoingCoins types.Currency `json:"unconfirmedoutgoingcoins"`
	UnconfirmedIncomingCoins types.Currency `json:"unconfirmedincomingcoins"`

	BlockStakeBalance types.Currency `json:"blockstakebalance"`
}

WalletGET contains general information about the wallet.

type WalletInitPOST

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

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

type WalletSeedsGET

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

WalletSeedsGET contains the seeds used by the wallet.

type WalletTransactionGETid

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

WalletTransactionGETid contains the transaction returned by a call to /wallet/transaction/$(id)

type WalletTransactionsGET

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

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)