Host and display the JSON-RPC schema in an easier to read format - Testnet

[devendran-m]

Request:

We can currently query the node: http://65.21.235.219:8888/rpc-schema.
Or use the Casper client subcommand list-rpcs.
MAKE created this URL for the previous version (1.0.0): http://casper-rpc-docs.s3-website-us-east-1.amazonaws.com/.
Please help create a similar link for the Testnet

Component: JSON-RPC
Assignee: SRE team
cc: @sacherjj @bradjohnl

[ipopescu]

@devendran-m can you please discuss this with the SRE team?

[RitaMAllenCA]

@sacherjj @bradjohnl Should this be in the SRE repo? Doesn't look like a docs issue

[sacherjj]

Rendering would only need to be done as part of a node release and eventually rpc sidecar release. But it should live on the docs site.

[bradjohnl]

After testing and analysis, I have concluded, also thanks to @andrzej-casper help, that it is currently not possible to render the OpenRPC API definition inside the JSONRPC documentation that gets produced by calling the casper-client list-rpcs function, using the OpenRPC provided libraries and tooling.

The main reason for that is due to a combinations of 2 things:

• The bug: FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory open-rpc/generator#689 on the generator tool, that makes it impossible to generate the documentation from our mainnet and testnenet docs, as the generator tool goes on infinite loops when circular references are detected in the JSON specification.

• The presence of circular references inside our generated specification.

I can provide more information with specific examples if needed, but for the sake of clarity, I am omitting them in this comment.

How do we move forward heavily depends on how much time and effort we want to dedicate on making this work.

1. Dive deeper into the libraries involved in the bug above, and submit a PR to fix the bug.
2. Create our own generator that loops through the JSON spec and generates the pretty documentation as html.
3. Try to implement proper referencing in the generated documentation so that circular references are eliminated or replaced with other constructs.

It's currently very hard to estimate the effort necessary for each course of action. TBH I think the option N.1 is probably the quickest, followed by a close battle between 2. and 3.
As the documentation is very long and complex, it might be an equally sizable effort to untangle it compared to creating our own pretty renderer.

@sacherjj @devendran-m @RitaMAllenCA

[RitaMAllenCA]

Moving this to the 2.0 timeframe for further consideration. We will organically be making updates to the RPC client and perhaps as part of that work we can reconsider this.

[ACStone-MTS]

Closing this ticket and #313 based on the discussions here in and the fact that we host the JSON-RPC API in its entirety on the docs site.