JSON-RPC API for nearcore node exposes handles to inspect the data, inspect the network state, and the node state, and allows to submit a transaction.
All the APIs that are compiled by default (default-features) and not prefixed
with EXPERIMENTAL_ are kept stable without breaking changes.
We also support near-api-* bindings to JSON-RPC in the latest state and
propagate deprecation warnings through them.
The breaking changes (e.g. removal or change of EXPERIMENTAL_ APIs) are
communicated through the CHANGELOG next to this file.
- We only add the APIs to the data that is already available in nearcore storage.
- We don't violate the guaranties described in the section above.
- We prefix new APIs with
EXPERIMENTAL_(see the Experimental API Policies below). - We document the API change on NEAR Docs BEFORE merging the change to nearcore.
- We log changes to the methods and API input/output structures through CHANGELOG.md file in the jsonrpc crate.
When you introduce new API, we may go two ways:
- Hide the new API behind a feature-flag that is not enabled by default
- Prefix the method name with
EXPERIMENTAL_
Either way, we need to document the new API in our RPC endpoint docs.
Stabilization of the Experimental APIs is multistage:
- Once the
EXPERIMENTAL_prefixed API handler lands to master it starts its lifetime. While the API is Experimental, we have the freedom to play with it and iterate fearlessly (if we need to change it, we change it and only record the change in the CHANGELOG and update the documentation, no need for backwards compatibility). - If we feel that the API is stable (being in use for a while), we need to
release a new API method without the
EXPERIMENTAL_prefix while keeping the old method name as an alias for the transition period. - Drop the
EXPERIMENTAL_alias completely when nearcore version with the stable method name is deployed to the majority nodes in the network, and most (all) clients have transitioned to the new API.