Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

EIP-1901: Add OpenRPC Service Discovery To JSON-RPC Services #1901

Merged
merged 15 commits into from
Jul 5, 2019
Merged
Changes from 11 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 78 additions & 0 deletions EIPS/eip-1901.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
---
eip: 1901
title: Add OpenRPC Service Discovery To JSON-RPC Services
author: Shane Jonas (@shanejonas), Zachary Belford (@belfordz)
discussions-to: https://github.com/ethereum/EIPs/issues/1902
status: Draft
type: Standards Track
category: Interface
created: 2019-02-25
---

# Abstract
axic marked this conversation as resolved.
Show resolved Hide resolved
### What is this?

This is a proposal to add [OpenRPC](https://github.com/open-rpc/spec) support to existing and future JSON-RPC services by adding the method [`rpc.discover`](https://github.com/open-rpc/spec#service-discovery-method) to the projects [JSON-RPC](https://www.jsonrpc.org/specification) APIs, enabling automation and tooling.

The OpenRPC Document and generated Documentation that specifies all the methods an EVM-based blockchain should implement can be found [here](https://github.com/etclabscore/ethereum-json-rpc-specification).

# Motivation
This was first proposed [here as an ECIP](https://github.com/etclabscore/ECIPs/blob/master/ECIPs/ECIP-1053.md), but the benefits of this kind of tooling is apparent across Bitcoin, Ethereum Classic, Ethereum and other JSON-RPC accessible blockchains.
shanejonas marked this conversation as resolved.
Show resolved Hide resolved

### What is the problem?
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is the primary motivation, you may want to word this section a bit more nicely.


- Maintenance 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](https://github.com/open-rpc/spec#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](https://www.jsonrpc.org/specification) system extensions.

### Use Case
This is the vision for the use case of OpenRPC and how it would relate to multi-geth:

![MultGethRpc-usecase](https://user-images.githubusercontent.com/364566/54172981-4605f480-443d-11e9-9e29-80c580f9edae.png)
axic marked this conversation as resolved.
Show resolved Hide resolved

# Specification

### What is OpenRPC?
The [OpenRPC](https://github.com/open-rpc/spec) Specification defines a standard, programming language-agnostic interface description for [JSON-RPC 2.0](https://www.jsonrpc.org/specification) 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:

![openrpc-spec-structure](https://github.com/open-rpc/design/raw/master/diagrams/structure/OpenRPC_structure.png)
axic marked this conversation as resolved.
Show resolved Hide resolved


# 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems to be part of the motivation. Rationale should explain how and what kind of decisions were made influencing the specification.


Use cases for machine-readable [JSON-RPC 2.0](https://www.jsonrpc.org/specification) 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](https://github.com/open-rpc/spec) documents just describe [JSON-RPC](https://www.jsonrpc.org/specification) 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`](https://github.com/open-rpc/spec#service-discovery-method) method. This gives projects and communities the flexibility to adopt tools before the [`rpc.discover`](https://github.com/open-rpc/spec#service-discovery-method) method is implemented.

## Resources

- [EDCON 2019 talk on OpenRPC and The Future of JSON-RPC Tooling](https://www.youtube.com/watch?v=UgSPMZ9FQ4Q)
- [open-rpc.org](https://open-rpc.org)
- [etclabscore/ethereum-json-rpc-specification](https://github.com/etclabscore/ethereum-json-rpc-specification)

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/) and code via [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0)
axic marked this conversation as resolved.
Show resolved Hide resolved