ECIP 1053: Add OpenRPC Service Discovery To JSON-RPC Services
| Author | Shane Jonas, Zachary Belford |
|---|---|
| Discussions-To | https://github.com/etclabscore/ECIPs/issues/16 |
| Status | Draft |
| Type | Standards Track |
| Category | Interface |
| Created | 2019-02-25 |
Abstract
What is this?
This is a proposal to add OpenRPC support to existing and future JSON-RPC services by adding the method rpc.discover to the projects JSON-RPC APIs, enabling automation and tooling.
Motivation
What is the problem?
- Maintenence time and accuracy on:
- documentation
- APIs
- clients
- Not all JSON-RPC servers return the same methods or return the same version of the API.
- There is nothing that provides both human and machine-readable interfaces to be able to interact with JSON-RPC.
- Communication between services in different programming languages is not easy.
- Implementation usually comes at the cost of user experience consuming the API.
Implementation
How do I Solve the problem?
JSON-RPC APIs can support the OpenRPC specification by implementing a service discovery method that will return the OpenRPC document for the JSON-RPC API. The method MUST be named rpc.discover. The rpc. prefix is a reserved method prefix for JSON-RPC 2.0 Specification system extensions.
Use Case
This is the vision for the use case of OpenRPC and how it would relate to multi-geth:
Specification
What is OpenRPC?
The OpenRPC Specification defines a standard, programming language-agnostic interface description for JSON-RPC 2.0 APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenRPC, a consumer can understand and interact with the remote service with a minimal amount of implementation logic, and share these logic patterns across use cases. Similar to what interface descriptions have done for lower-level programming, the OpenRPC Specification removes guesswork in calling a service.
Structure
This is the structure of an OpenRPC Document:
The OpenRPC Document that specifies all the methods an EVM-based blockchain should implement can be found here.
Rationale
Why would we do this?
Services need to figure out how to talk to each other. If we really want to build the next generation of automation, then having up to date libraries, documented APIs, and modern tools are going to provide easy discovery, on-boarding, and enable end user and developer interaction.
Use cases for machine-readable JSON-RPC 2.0 API definition documents include, but are not limited to:
- A common vocabulary and document will keep developers, testers, architects, and technical writers all in sync.
- Server stubs/skeletons generated in many languages
- Clients generated in many languages
- Mock Server generated in many languages
- Tests generated in many languages
- Documentation Generation
Alternative
OpenRPC documents just describe JSON-RPC APIs services, and are represented in JSON format. These documents may be produced and served statically OR generated dynamically from an application and returned via the rpc.discover method. This gives projects and communities the flexibility to adopt tools before the rpc.discover method is implemented.