Eth Beacon Node API
Agora-cl supports the official Eth Beacon Node API specification, the official API standard developed by the Ethereum R&D team. The specification describes a RESTful set of endpoints which should be implemented by an Eth Agora node or a third-party service. This reduces the overhead of having to learn a new set of APIs when trying out a different client, and it allows network participants to reliably talk to each other over HTTP. As an example of an external service implementing the spec, Infura's Agora chain API is described here.
Performing requests against a local Agora-cl node
The API's purpose is a means of communication between your Agora node and your validator client. Because of this it is not protected against external malicious users. Some endpoints are vulnerable to Denial-of-Service attacks, while others may disclose information about your Agora node. The communication between the Agora node and the validator client should be done privately, either on the same machine or through an SSH connection.
The API is exposed by default on 127.0.0.1:3500. The host can be changed by manipulating the --grpc-gateway-host flag and the port can be modified with the --grpc-gateway-port flag. Performing a request is straightforward - simply concatenate the host with the port and the API's URL, providing any required URL and query parameters. As an example, the finalized state's root can be obtained using:
http://127.0.0.1:3500/eth/v1/beacon/states/finalized/root
Notice that in this example the {state_id} URL parameter has been replaced with the literal value finalized. Please read the specification carefully to understand how each endpoint behaves.
Disabling the API
By default the Agora node runs with all available set of APIs enabled. You might want to disable one or more APIs, for example for security reasons. The --http-modules flags allows fine-grained control over which APIs are available on your node.
Tips and Recommendations
If you're experiencing timeouts when using endpoints that require passing a state_id, such as /eth/v1/beacon/states/{state_id}/validators, and you pass in a state more than a few epochs in the past, consider lowering the value of the --slots-per-archive-point flag. The smaller the value, the faster it is to fetch states. For historical state fetching we recommend setting the value to 64 or even 32. Mind you that decreasing the value will result in the beacon DB taking much more space. Unfortunately there's a trade-off between speed and storage size.