RPC API breaking changes are not detected by CI

[jstarry]

Problem

We have no way to detect breaking changes to the JSON-RPC API through CI right now. This makes it easy to move quickly and break the api, but makes it hard to enforce a process for raising awareness to these changes.

Proposed Solution

WIP

[jstarry]

Unfortunately cannot use OpenAPI because our json rpc http server uses a single endpoint which has different behavior for different request bodies (rpc method name and params) and there is no way to link a particular request body schema with a response schema. Context: https://swagger.io/docs/specification/describing-responses/#faq

[mvines]

I'm not totally opposed to a massive breaking change if it gets us on a well-supported standard path that enforces best practices. We mostly built up our existing RPC organically and in a vacuum. More breaking API pain for sure, but if it's going to be a long term win I'm down.

[jstarry]

JSON-RPC

Quite a few projects are using JSON-RPC apis (Ethereum, Near, Nervos, Polkadot, etc) not that that's a good enough reason alone to stick with that approach. For instance, there are a number of complaints about the lack of a standard spec or documentation for the APIs of different Ethereum clients.

If we stick with JSON-RPC we could collaborate on the recent OpenRPC effort which is being led by members of the Eth Classic community for this project. We could also just roll our own testing by defining our API spec with https://json-schema.org/. (I also looked into AsyncAPI more and it's not well-suited to RPC over HTTP)

GraphQL

GraphQL is getting pretty popular these days and is built to avoid breaking changes and API versioning so we wouldn't need a spec format for it. There are a few popular Rust libraries for the server and client (which supports wasm 🎉).

There's an EIP to adopt it for Ethereum and parity plans to include support once the Rust graphql server library releases an update for async-await support. There are also a couple of independent projects building graphql apis for various chains:

• https://github.com/ConsenSys/ethql (eth)
• https://astrograph.io/ (stellar)
• https://thegraph.com/ (general)

I wouldn't be surprised if GraphQL gains more traction and more projects switch over to it in the future. Seems well suited to the type of querying dapps would need. It only returns the data that you ask for, which makes it really great for mobile / web.

REST

If we switch to a REST API we could leverage OpenAPI and generate clients from that. Algorand is doing this and provides SDKs in a number languages that are partially generated using the OpenAPI spec. Looks pretty nice!

[CriesofCarrots]

Neat, thanks for all the research, @jstarry !
I think the GraphQL idea is pretty exciting. It seems to have a much stronger foothold in the blockchain community now.
I assume a top priority for us here should be users transitioning from other projects to solana. Do you have a feel for the extent of GraphQL apis being used by clients in the wild?

[jstarry]

I assume a top priority for us here should be users transitioning from other projects to solana.

Yeah, I think that's a priority since most of the existing learning resources for dapp development are geared towards Ethereum. I'm not sure we expect many existing projects to migrate to Solana though. For that reason I think we have some wiggle room in how we approach things.

Do you have a feel for the extent of GraphQL apis being used by clients in the wild?

Looks like dfuse has a lot of traction in the EOS community but it's not clear which of the APIs they offer are the most popular (they offer GraphQL, WebSocket, and REST). I think it's safe to assume that GraphQL is used a fair bit. Here's the JS client they offer: https://github.com/dfuse-io/client-js

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.

[stale]

This stale issue has been automatically closed. Thank you for your contributions.