Overview

The Node API is a specification for both blockchain data format and a communication pattern for interacting with a blockchain node. Any implementations of this specification are also expected to provide a configuration for automated deployment of their implementation using a Dockerfile.

For a full list of expectations of any Node API implementation, please take a look at the documents in the Expectations section. We also recommend taking a look at the Common Mistakes page for a list of a few mistakes implementers tend to make when meeting these expectations.

Standard, JSON-Based RPC Protocol

When working on this API, we considered many interface specification formats that have gained popularity in recent years (like Protobuf + gRPC and Avro) but found most only had strong support for a few programming languages, required users to have enough programming experience to know how to use autogenerated code to encode/decode some binary format, and/or didn't work well in the browser.

The Rosetta Node API is specified in the OpenAPI 3.0 format (the successor to Swagger/OpenAPI 2.0). Requests and responses can be crafted with autogenerated code using Swagger Codegen or OpenAPI Generator (with the downloadable JSON spec at the top of this site), are human-readable (easy to debug and understand), and can be used in servers and browsers. Using JSON incurs some performance penalty, however, we have found the challenge of robust integration to be a much more painful issue than mitigating JSON overhead.

Due to the complexity of requests (which can often contain a number of parameters of unspecified size), all communication with the Rosetta Interface Server utilizes HTTP POST requests. This makes the interface much closer to JSON-RPC 2.0 with the exception that requests go to specific paths instead of using methods. If you have used gRPC, it will feel very familiar.

Automated Node Deployment

There are many projects that allow you to configure and manage the automated deployment of a service. From our experience, we have found that the small learning curve, mature tooling, generality, and widespread ecosystem support of Docker make for a relatively painless and sufficiently reliable deployment.

Upon first glance, using a single Dockerfile to start all services required by the node may sound antithetical to best practices. However, we have found that restricting blockchain node deployment to a single container makes the orchestration of multiple nodes much easier because of coordinated start/stop and single volume mounting.