Design and Features of the Oasis API Server

August 17, 2020 ยท View on GitHub

This page will present the inner workings of the API Server as well as the features that one is able to interact with and how. The following points will be presented and discussed:

Design

The components involved in the API Server are the following:

  • The Oasis Nodes from which the API retrieves information
  • This API Server uses multiple Oasis API clients to retrieve data from the Oasis nodes.
  • The User/Program which sends GET Requests to the API Server as per the defined endpoints, and receives JSON formatted responses from the API Server

The diagram below gives an idea of the various components at play when the API Server is running, and how they interact with each other and the user/program:

design

The API Server works as follows:

  • The API Server loads the configuration containing the internal socket information for each node from the config/user_config_nodes.ini file together with Prometheus endpoints that are used to query blockchain data.
  • The API Server loads the API server configuration from the config/user_config_main.ini file together with the Node Exporter endpoint which will be used to query machine data.
  • The API Server has an option to also retrieve the data of Sentries connected to the node through the External URl and tls certificate data of the Sentry. This data is set up in the config/user_config_sentry file.
  • By communicating through this port, the API Server receives the endpoints specified in the Complete List of Endpoints section below, and requests information from the nodes it is connected to accordingly.
  • Once a request is received for an endpoint the server will read the query which should contain the name of the node that will be queried, it then attempts to establish a connection to the node and request data from it. This data is then foramtted into JSON and returned.
  • The server interacts with the protocol API through these clients :
    1. Consensus Client
    2. Registry Backend
    3. Staking Backend
    4. Scheduler Backend
    5. NodeController
    6. Sentry

Complete List of Endpoints

API EndpointRequired InputsOptional InputsOutput
/api/pingnonenonePong
/api/getconnectionslistnonenoneList of Connections
/api/consensus/genesisNode NameHeightConsensus Genesis State
/api/consensus/genesisdocumentNode NameOriginal Genesis Document
/api/consensus/epochNode NameHeightEpoch
/api/consensus/statusNode NameNode Status
/api/consensus/blockNode NameHeightBlock Object
/api/consensus/blockheaderNode NameHeightBlock Header Object
/api/consensus/blocklastcommitNode NameHeightBlock Last Commit Object
/api/consensus/pubkeyaddressConsensus Public KeynoneTendermint Key Address
/api/consensus/transactionsNode NameHeightList of Transactions
/api/pingnodeNode NameNonePong
/api/registry/entitiesNode NameHeightList of entities
/api/registry/nodesNode NameHeightList of Nodes
/api/registry/runtimesNode NameHeightList of RunTimes
/api/registry/genesisNode NameHeightGenesis State of Registry
/api/registry/entityNode Name, Entity Public KeyHeightEntity
/api/registry/nodeNode Name, Node Public KeyHeightNode
/api/registry/nodestatusNode Name, Node Public KeyHeightNode Status
/api/registry/eventsNode NameHeightRegistry Events
/api/registry/runtimeNode Name, Runtime NamespaceHeightRuntime
/api/registry/runtimesNode Name, Suspended BooleanHeightRuntimes
/api/staking/totalsupplyNode NameHeightTotal Supply
/api/staking/commonpoolNode NameHeightCommon Pool
/api/staking/lastblockfeesNode NameHeightLast Block Fees
/api/staking/genesisNode NameHeightStaking Genesis State
/api/staking/thresholdNode Name, kindHeightThreshold
/api/staking/addressesNode NameHeightList of accounts
/api/staking/accountNode Name, Account AddressHeightAccount information
/api/staking/delegationsNode Name, Account AddressHeightDelegations
/api/staking/debondingdelegationsNode Name, Account AddressHeightDebondingDelegations
/api/staking/eventsNode NameHeightList of Events
/api/staking/publickeytoaddressPublic KeyStaking Address
/api/nodecontroller/syncedNode NameNoneSynchronized State
/api/scheduler/validatorsNode NameHeightList of Validators
/api/scheduler/committeesNode Name, NamespaceHeightCommittees
/api/scheduler/genesisNode NameHeightScheduler Genesis State
/api/prometheus/gaugeNode Name, Gauge NamenoneGauge Value
/api/prometheus/counterNode Name, Counter NamenoneCounter Value
/api/exporter/gaugeGauge NamenoneGauge Value
/api/exporter/counterCounter NamenoneCounter Value
/api/sentry/addressesNode NamenoneNodes Connected to Sentry

Example Queries

This is a list of example queries with the exact parameters and a custom node Oasis_Main_Validator being pinged from localhost 127.0.0.1.

API EndpointQuery
/api/ping127.0.0.1:8686/api/ping
/api/getconnectionslist127.0.0.1:8686/api/getconnectionslist
/api/consensus/genesis127.0.0.1:8686/api/consensus/genesis?name=Oasis_Main_Validator&height=1000
/api/consensus/genesisdocument127.0.0.1:8686/api/consensus/genesisdocument?name=Oasis_Main_Validator&height=1000
/api/consensus/epoch127.0.0.1:8686/api/consensus/epoch?name=Oasis_Main_Validator&height=1000
/api/consensus/status127.0.0.1:8686/api/consensus/status?name=Oasis_Main_Validator&height=1000
/api/consensus/block127.0.0.1:8686/api/consensus/block?name=Oasis_Main_Validator&height=1000
/api/consensus/blockheader127.0.0.1:8686/api/consensus/blockheader?name=Oasis_Main_Validator&height=1000
/api/consensus/blocklastcommit127.0.0.1:8686/api/consensus/blocklastcommit?name=Oasis_Main_Validator&height=1000
/api/consensus/pubkeyaddress127.0.0.1:8686/api/consensus/pubkeyaddress?consensus_public_key=AzJTHgUZKYGYVPoN5F8WLtMyEPh7OKpM1uJGQVRiZek=
/api/consensus/transactions127.0.0.1:8686/api/consensus/transactions?name=Oasis_Main_Validator&height=1000
/api/pingnode127.0.0.1:8686/api/pingnode?name=Oasis_Main_Validator
/api/registry/entities127.0.0.1:8686/api/registry/entities?name=Oasis_Main_Validator&height=1000
/api/registry/nodes127.0.0.1:8686/api/registry/nodes?name=Oasis_Main_Validator&height=1000
/api/registry/runtimes127.0.0.1:8686/api/registry/runtimes?name=Oasis_Main_Validator&height=1000
/api/registry/genesis127.0.0.1:8686/api/registry/genesis?name=Oasis_Main_Validator&height=1000
/api/registry/entity127.0.0.1:8686/api/registry/entity?name=Oasis_Main_Validator&height=1000&entity=gb8SHLeDc69Elk7OTfqhtVgE2sqxrBCDQI84xKR+Bjg=
/api/registry/node127.0.0.1:8686/api/registry/node?name=Oasis_Main_Validator&height=1000&nodeID=5RIMVgnsN1D/HdvNxXCpE+lWH5U/SGYUrYsvhsTMbyA=
/api/registry/nodestatus127.0.0.1:8686/api/registry/nodestatus?name=Oasis_Main_Validator&height=1000&nodeID=5RIMVgnsN1D/HdvNxXCpE+lWH5U/SGYUrYsvhsTMbyA=
/api/registry/events127.0.0.1:8686/api/registry/events?name=Oasis_Main_Validator&height=1000
/api/registry/runtime127.0.0.1:8686/api/registry/runtime?name=Oasis_Main_Validator&height=1000&namespace=6XJLXaerB2A/HdvNxXCpE+lWH5U/SGYUrXsvhsTMbyB=
/api/registry/runtimes127.0.0.1:8686/api/registry/runtimes?name=Oasis_Main_Validator&height=1000&suspended=true
/api/staking/totalsupply127.0.0.1:8686/api/staking/totalsupply?name=Oasis_Main_Validator&height=1000
/api/staking/commonpool127.0.0.1:8686/api/staking/commonpool?name=Oasis_Main_Validator&height=1000
/api/staking/lastblockfees127.0.0.1:8686/api/staking/lastblockfees?name=Oasis_Main_Validator&height=1000
/api/staking/genesis127.0.0.1:8686/api/staking/genesis?name=Oasis_Main_Validator&height=1000
/api/staking/threshold127.0.0.1:8686/api/staking/threshold?name=Oasis_Main_Validator&height=1000&kind=1
/api/staking/addresses127.0.0.1:8686/api/staking/addresses?name=Oasis_Main_Validator&height=1000
/api/staking/account127.0.0.1:8686/api/staking/account?name=Oasis_Main_Validator&height=1000&address=oasis1qqqf342r78nz05dq2pa3wzh0w54k3ea49u6rqdhv
/api/staking/delegations127.0.0.1:8686/api/staking/delegations?name=Oasis_Main_Validator&height=1000&address=oasis1qqqf342r78nz05dq2pa3wzh0w54k3ea49u6rqdhv
/api/staking/debondingdelegations127.0.0.1:8686/api/staking/debondingdelegations?name=Oasis_Main_Validator&height=1000&address=oasis1qqqf342r78nz05dq2pa3wzh0w54k3ea49u6rqdhv
/api/staking/events127.0.0.1:8686/api/staking/events?name=Oasis_Main_Validator&height=1000
/api/staking/publickeytoaddress127.0.0.1:8686/api/staking/publickeytoaddress?pubKey=BKNMlGLov7tJZi4Gopeu0sXGxXWvg1uKDfY4wNY3WCM=
/api/nodecontroller/synced127.0.0.1:8686/api/nodecontroller/synced?name=Oasis_Main_Validator
/api/scheduler/validators127.0.0.1:8686/api/scheduler/validators?name=Oasis_Main_Validator&height=1000
/api/scheduler/committees127.0.0.1:8686/api/scheduler/committees?name=Oasis_Main_Validator&height=1000&namespace=6XJLXaerB2A/HdvNxXCpE+lWH5U/SGYUrXsvhsTMbyB=
/api/scheduler/genesis127.0.0.1:8686/api/scheduler/genesis?name=Oasis_Main_Validator&height=1000
/api/prometheus/gauge127.0.0.1:8686/api/prometheus/gauge?name=Oasis_Main_Validator&gauge=go_goroutines
/api/prometheus/counter127.0.0.1:8686/api/prometheus/counter?name=Oasis_Main_Validator&gauge=go_memstats_alloc_bytes_total
/api/exporter/gauge127.0.0.1:8686/api/exporter/gauge?gauge=node_nf_conntrack_entries
/api/exporter/counter127.0.0.1:8686/api/exporter/counter?counter=node_timex_pps_calibration_total
/api/sentry/addresses127.0.0.1:8686/api/sentry/addresses?name=Oasis_Main_Validator

Using the API

To use the API one can either go in the browser and type in the URL that has the IP address of your running server, for example : http://127.0.0.1:8686/api/consensus/blockheader?name=Oasis_Main_Validator&height=1000 or in the command line they can use the curl command to query it, for example : curl "127.0.0.1:8686/api/consensus/blockheader?name=Oasis_Main_Validator&height=1000".

Back to API front page