# JSON-RPC API documentation ## Context - Matt mantains: - https://github.com/ethereum/execution-apis/ - https://ethereum.github.io/execution-apis/api-documentation/ - Built on https://github.com/open-rpc/playground - the open-rpc/playground was built by some ethereum classic folks (who have now moved on, i think one still sort of watches the open-rpc stuff because he works for metamask and they use it for their wallet namespace docs) and it's okay but it could really use some tweaks to be better formatted - Geth team has ideas on: - improving this app - Ethereum RPC API documentation in general - Questions - Felix: are you guys willing to help out with tweaking this 'playground' thing? - Felix: IMHO that app looks over-complicated, it's spread across multiple node.js packages. It works though. - Felix: Alternatively, we could think about integrating the execution-apis content into the ethereum.org app. Like having a section on the site that shows the JSON-RPC API methods and some info about their parameters. I bet it's not super complicated to make this. ## Call notes - Matt is now working on Geth - Focusing on the non-standard JSON RPC APIs Geth provides (e.g. debugging) - No good way to show these specs. How to standardize these APIs? - Working on RPC standards & bringing those in - https://github.com/ethereum/execution-apis/ - Standardization process - How's it work now? How does a new method become standard? - No longer goes through the EIP process, e.g. https://github.com/ethereum/EIPs/pull/3361 - Typically clients create a namespace for their custom APIs (e.g. Partiy tracing APIs that Nethermind now mimics). So client adoption comes somewhat organically - clients tend to replicate endpoints of others - Matt has tried to formalize minimal subset of client APIs as a standard - Rough process? - e.g. contributor submits PR for new API endpoint to Geth, Felix now pushes people to the specs repo: open an issue/PR there first. Now pushing to formalize the process behind the spec. e.g. https://github.com/ethereum/execution-apis/issues/224 - How do clients document? - Currently on their own: - https://docs.nethermind.io/nethermind/ethereum-client/json-rpc/eth - https://geth.ethereum.org/docs/rpc/server - Should this continue to be the case (probably)? - Vision - Currently we are developing spec agaisnt clients - Endgoal: we want to do the reverse - We want tests we can run against all clients to confirm they all implement the endpoints the same way - Downstream tooling and infrastructure should be able to treat different Ethereum clients as modules that can be swapped at will - How do we accomplish this? - Spec - Now have unified, canoncial spec (https://github.com/ethereum/execution-apis/) - Just need a solid way for everyone to be able to ingest & reference it - This is where playground comes in... - e.g. MM using a version of this: https://metamask.github.io/api-playground/api-documentation/ - API - Methods - Methods have parameters - e.g. block number - schema of parameters - Documenting entities separately? - e.g. https://geth.ethereum.org/docs/rpc/objects - Hive project - https://github.com/ethereum/hive - Docker to run each client - Simulators for each client - Could add tests that hit each RPC endpoint for each client & confirm it works as expected - e.g. https://github.com/lightclient/rpctests (only a couple so far) - Playground - https://ethereum.github.io/execution-apis/api-documentation/ - Built on https://github.com/open-rpc/playground - Playground issues - Open RPC playground is good, not great - It's a bit clunky - e.g. menu is dumb, homepage is silly - doesn't appear to render markdown (correctly) - Nice that it's formal but needs to be flatter - Flat lists of the methods you can get - Hard to inspect e.g. looking at parameters of methods - Structure/hiearchy - No mention of abstract use cases. Some methods are for e.g. submission of txs. Send txs send raw txs but also have signed txs. Can we group these methods together? Some place that categorizes these? - `eth_sendTransaction` - `eth_sendRawTransaction` - hard to convey that information in this format - In spec, there's some of this - categorized by e.g. methods for blocks, getting info from the client, the spec breaks this out by files - Perhaps some 2-pane documentation - 1. Practical use cases / way to categorize - 2. Formal list - What is supported? - e.g. arbitrary summary text / overview of methods? - Could we attach a bunch of text into each method? Arbitrary markdown? - Need to confirm what's currently possible here... - Method schema vs. components - Format of source - https://spec.open-rpc.org/#info-object - Considering moving to yaml - easier to write long-form (this is hard in JSON) - What to optimize for? - Make spec & docs as easy to read as possible - Playground is nice additional feature - Generating docs vs. manual descriptions - Opted for generated docs. Not as flexible / user-friendly but helps to keep everything in sync - Downsides of manual? Do we have the people/resources to keep things in sync? So far in Ethereum's history this has not been the case... lots of outdated docs/resources - Who is working on this? Who can? - Right now, just Matt :) - What are the needs? - Primarily a React/TS dev who can investigate customizing OpenRPC playground - Get some quick wins, e.g. - flexible markdown descriptions to methods? - general blob field that can render arbitrary markdown? - flatter view of parameters - URL (/api-documentation) vs root: kill splash page? - Design/UX improvements - Styling: overall it's plain/generic looking - e.g. panels to view methods by category/use case vs. alphabetical order - reconsider architecture of how to present - Good examples? - Docker docs - Organizes API into use cases - Example outputs (response samples) - 200, 400 bad params, 500 server error - Content - Better explanations of methods ## Action items - [x] Sam to clean up notes - [ ] Sam to ping Matt for specs out what changes we want to need