Maintenance and other services endpoints

There are several endpoints you can use to query or update information about a Chainweb node, including its current configuration and availability.

Use POST http://{baseURL}/make-backup to start a backup job for a Chainweb node. Starting a backup job creates a UNIX timestamp identifier for the job. You can then use the identifier to check the status of the job to determine if the job is still in progress or the backup has been completed.

If a backup job is already in progress, this endpoint returns the UNIX timestamp job identifier instead of starting a new backup job.

The POST http://{baseURL}/make-backup endpoint is only valid if you enable the backup API for a node. You can enable the backup API by starting the node with the --enable-backup-api and --backup-directory command-line options or by specifying the following configuration settings in the node configuration file:

If you enable the backup API, sending a request the POST http://{baseURL}/make-backup endpoint always backs up the RocksDB portion of the Chainweb database.

In most cases, you should locate the backup directory in the same partition as the active RocksDB database. Storing RocksDB backups in the same partition as the active RocksDB database minimizes the space required and the time it takes to complete backups initially. Over time—as the active database diverges from the backup copy—the space required will increase. If you store the backup on another partition, the backup operation takes longer and the backup copy requires as much disk space as the active RocksDB database.

Chainweb nodes have two separate databases. One database—the RocksDB database—stores information about blocks and chains. A second database—the Pact Sqlite database—stores information about smart contracts and state.

While backup jobs always back up the RocksDB database, backing up the Pact Sqlite database is optional. If you include the backupPact parameter in your request, the backup job backs up both databases. Backing up both databases takes much longer than only backing up the RockDB database. In addition, Pact database backups always require as much space as the active Pact database.

Database backup jobs don't provide any type of automatic backup retention policy. You should define your own policy and delete old backup copies, as appropriate.

Requests to the POST http://{baseURL}/make-backup endpoint return the following response code:

The response header parameters are the same for all successful and unsuccessful Chainweb node requests.

The response returns text/plain content with the following information:

Use GET http://{baseURL}/check-backup/{backupId} to check the status of a backup job.

Requests to the GET http://{baseURL}/check-backup endpoint can return the following response codes:

The response header parameters are the same for all successful and unsuccessful Chainweb node requests.

The response returns text/plain content with the following information:

Use GET http://{baseURL}/health-check to check whether chainweb-node is running and responding to API requests. To check the state of consensus, you should use the GET https://{baseURL}/cut endpoint instead of this endpoint.

Requests to the /health-check endpoint return the following response code:

The response header parameters are the same for all successful and unsuccessful Chainweb node requests.

The response returns text/plain content with the following information:

You can send a health check request to a node like this:

This request returns a plain text message like this:

Use GET http://{baseURL}/info to return general information about the node and the Chainweb version.

Requests to the GET http://{baseURL}/info endpoint return the following response code:

The response header parameters are the same for all successful and unsuccessful Chainweb node requests.

If the request is successful, the response returns application/json content with the following:

You can send a request for general information to a node like this:

This request returns information similar to the following truncated excerpt:

Use GET http://{baseURL}/header/updates to connect to a source of server events that emits a BlockHeader event for each new block header that is added to the chain database of the remote node.

The stream can contain blocks that might later become orphaned. To address this potential issue, you should buffer events on the client side for the most recent block heights to allow for a desired confirmation depth to be reached.

You should note that the server might terminate this event stream from time to time. It is up to the client to restart event streaming with a new request.

The response header parameters are the same for all successful and unsuccessful Chainweb node requests.

If the request is successful, the response returns text/event-stream content with the following:

You can send a request for block header updates from the Kadena main network like this:

This request returns a stream of events with the BlockHeader event property and a data property:

If you expand the data property for an event, the event includes details similar to the folloiwng: