improve rest api documentation: first draft (#3306)
* rest api: first draft * minor edit * Update docs/the_nimbus_book/src/rest-api.md Co-authored-by: Jacek Sieka <jacek@status.im> * Update docs/the_nimbus_book/src/rest-api.md Co-authored-by: Jacek Sieka <jacek@status.im> * Update docs/the_nimbus_book/src/rest-api.md Co-authored-by: Jacek Sieka <jacek@status.im> * incorporate feedback Co-authored-by: Jacek Sieka <jacek@status.im>
This commit is contained in:
sacha
GitHub
parent
54a745cb0e
commit
b7b517d97e
|
|
@ -1,31 +1,173 @@
|
|||
# REST API
|
||||
|
||||
Nimbus exposes a high-performance implementation of the [Beacon Node API](https://ethereum.github.io/beacon-APIs/).
|
||||
Nimbus exposes an **extremely fast** and high-performance implementation of the standard [Beacon Node API](https://ethereum.github.io/beacon-APIs/). The API allows you to use Nimbus together with third-party tooling such as validator clients, block explorers as well as your own monitoring infrastructure.
|
||||
|
||||
The API is a `REST` interface accessed via `HTTP`. The API should not, unless protected by additional security layers, be exposed to the public Internet as the API includes multiple endpoints which could open your node to denial-of-service (DoS) attacks.
|
||||
The API is a `REST` interface accessed via `HTTP`. **The API should not be exposed to the public Internet** unless protected by additional security: it includes multiple endpoints which could open your node to denial-of-service (DoS) attacks.
|
||||
|
||||
The API can be used with any conforming consumer, including alternative validator client implementations, explorers and tooling.
|
||||
|
||||
## Configuration
|
||||
## Test your tooling against our servers
|
||||
|
||||
By default, the REST interface is disabled. To enable it, start the beacon node with the `--rest` option, then access the API from http://localhost:5052/.
|
||||
The API is available from:
|
||||
|
||||
> **Warning:** If you are using a validator client with a Nimbus beacon node, and running a Nimbus version prior to `v1.5.5`, then you will need to launch the node with the `--subscribe-all-subnets` option enabled.
|
||||
* `http://testing.mainnet.beacon-api.nimbus.team/`
|
||||
* `http://unstable.mainnet.beacon-api.nimbus.team/`
|
||||
* `http://unstable.prater.beacon-api.nimbus.team/`
|
||||
|
||||
You can make requests as follows (here we are requesting the version the Nimbus software version of the node in question):
|
||||
|
||||
#### Mainnet testing branch
|
||||
```
|
||||
curl -X GET http://testing.mainnet.beacon-api.nimbus.team/eth/v1/node/version
|
||||
```
|
||||
|
||||
#### Mainnet unstable branch
|
||||
```
|
||||
curl -X GET http://unstable.mainnet.beacon-api.nimbus.team/eth/v1/node/version
|
||||
```
|
||||
|
||||
#### Prater unstable branch
|
||||
```
|
||||
curl -X GET http://unstable.prater.beacon-api.nimbus.team/eth/v1/node/version
|
||||
```
|
||||
|
||||
The test endpoints are part of pre-release testing and run an unstable version of Nimbus - we welcome reports about any problems you might have with them.
|
||||
|
||||
They may also be unresponsive at times - so **please do not rely on them for validation**. We may also disable them at any time without warning.
|
||||
|
||||
|
||||
## Configure your node to run a local REST server
|
||||
|
||||
By default, the REST interface is disabled. To enable it, start the beacon node with the `--rest` option:
|
||||
|
||||
```
|
||||
./run-mainnet-beacon-node.sh --rest
|
||||
```
|
||||
|
||||
Then access the API from `http://localhost:5052/`. For example, to get the version of the Nimbus software your node is running:
|
||||
|
||||
```
|
||||
curl -X GET http://localhost:5052/eth/v1/node/version
|
||||
```
|
||||
|
||||
By default, only connections from the same machine are entertained. The port and listening address can be further configured through the options `--rest-port` and `--rest-address`.
|
||||
|
||||
> **Warning:** If you are using a validator client with a Nimbus beacon node, and running a Nimbus version prior to `v1.5.5`, then you will need to launch the node with the `--subscribe-all-subnets` option enabled (in addition to the `--rest` option).
|
||||
|
||||
## Some useful commands
|
||||
|
||||
### Standard endpoints
|
||||
|
||||
While these are all well documented in the [official docs](https://ethereum.github.io/beacon-APIs/) here are a handful of simple examples to get you started:
|
||||
|
||||
#### Genesis
|
||||
|
||||
Retrieve details of the chain's genesis which can be used to identify chain.
|
||||
|
||||
*With our mainnet testing server*
|
||||
```
|
||||
curl -X GET http://unstable.mainnet.beacon-api.nimbus.team/eth/v1/beacon/genesis
|
||||
```
|
||||
|
||||
*With your own local server*
|
||||
```
|
||||
curl -X GET http://localhost:5052/eth/v1/beacon/genesis
|
||||
```
|
||||
|
||||
#### Deposit contract
|
||||
|
||||
Get deposit contract address (retrieve Eth1 deposit contract address and chain ID).
|
||||
|
||||
*With our mainnet testing server*
|
||||
```
|
||||
curl -X GET http://unstable.mainnet.beacon-api.nimbus.team/eth/v1/config/deposit_contract
|
||||
```
|
||||
|
||||
*With your own local server*
|
||||
```
|
||||
curl -X GET http://localhost:5052/eth/v1/config/deposit_contract
|
||||
```
|
||||
|
||||
|
||||
#### Peer count
|
||||
|
||||
Get peer count
|
||||
|
||||
*With our mainnet testing server*
|
||||
```
|
||||
curl -X GET http://unstable.mainnet.beacon-api.nimbus.team/eth/v1/node/peer_count
|
||||
```
|
||||
|
||||
*With your own local server*
|
||||
```
|
||||
curl -X GET http://localhost:5052/eth/v1/node/peer_count
|
||||
```
|
||||
|
||||
|
||||
#### Syncing status
|
||||
|
||||
Get node syncing status (requests the beacon node to describe if it's currently syncing or not, and if it is, what block it is up to)
|
||||
|
||||
*With our mainnet testing server*
|
||||
```
|
||||
curl -X GET http://unstable.mainnet.beacon-api.nimbus.team/eth/v1/node/syncing
|
||||
```
|
||||
|
||||
*With your own local server*
|
||||
```
|
||||
curl -X GET http://localhost:5052/eth/v1/node/syncing
|
||||
```
|
||||
|
||||
#### Fork schedule
|
||||
|
||||
Get scheduled upcoming forks (retrieve all forks, past present and future, of which this node is aware)
|
||||
|
||||
*With our mainnet testing server*
|
||||
```
|
||||
curl -X GET http://unstable.mainnet.beacon-api.nimbus.team/eth/v1/config/fork_schedule
|
||||
```
|
||||
|
||||
*With your own local server*
|
||||
```
|
||||
curl -X GET http://localhost:5052/eth/v1/config/fork_schedule
|
||||
```
|
||||
|
||||
|
||||
### Nimbus specific endpoints
|
||||
|
||||
In addition to supporting the standard endpoints, Nimbus has a set of specific endpoints which augment the standard API.
|
||||
|
||||
|
||||
#### Check Graffiti String
|
||||
|
||||
|
||||
*With our mainnet testing server*
|
||||
|
||||
```
|
||||
curl -X GET http://testing.mainnet.beacon-api.nimbus.team/nimbus/v1/graffiti
|
||||
```
|
||||
|
||||
*With your own local server*
|
||||
```
|
||||
curl -X GET http://localhost:5052/nimbus/v1/graffiti
|
||||
```
|
||||
|
||||
#### Set Graffiti String
|
||||
|
||||
*With your own local server*
|
||||
```
|
||||
curl -X POST http://localhost:5052/nimbus/v1/graffiti -H "Content-Type: text/plain" -d "new graffiti"
|
||||
```
|
||||
|
||||
#### Set Log Level
|
||||
|
||||
*TBA*
|
||||
|
||||
|
||||
|
||||
## Specification
|
||||
|
||||
The specification is documented [here](https://ethereum.github.io/beacon-APIs/).
|
||||
- The complete API specification is well documented [here](https://ethereum.github.io/beacon-APIs/)
|
||||
|
||||
See the Readme [here](https://github.com/ethereum/beacon-APIs).
|
||||
- See the repository Readme [here](https://github.com/ethereum/beacon-APIs)
|
||||
|
||||
## Quickly test your tooling against Nimbus
|
||||
|
||||
The [Nimbus REST api](https://nimbus.guide/rest-api.html) is now available from:
|
||||
|
||||
* http://testing.mainnet.beacon-api.nimbus.team/
|
||||
* http://unstable.mainnet.beacon-api.nimbus.team/
|
||||
* http://unstable.prater.beacon-api.nimbus.team/
|
||||
|
||||
Note that right now these are very much unstable testing instances. They may be unresponsive at times - so **please do not rely on them for validation**. We may also disable them at any time.
|
||||
|
|
|
|||
Loading…
Reference in New Issue