[DOC] Undocumented RPC endpoints

[telezhnaya]

Here, we have a number of undocumented RPC endpoints. + and nickname near the method means this person agreed to cover it with the doc.

• [ ] health
• [ ] light_client_proof - @posvyatokum
• [x] network_routes - @saketh-are
• [ ] next_light_client_block
• [x] tier1_network_info - @saketh-are
• [ ] EXPERIMENTAL_broadcast_tx_sync
• [ ] EXPERIMENTAL_check_tx
• [ ] EXPERIMENTAL_light_client_proof - @posvyatokum
• [ ] EXPERIMENTAL_validators_ordered
• [ ] EXPERIMENTAL_maintenance_windows
• [ ] EXPERIMENTAL_split_storage_info
• [ ] query:
  • [ ] view_state
  • [ ] include_proof flag

@bowenwang1996 @ailisp @mina86 @saketh-are, please tag the other authors as well

[telezhnaya]

Also, the flag include_proof was never documented https://docs.near.org/api/rpc/contracts Added by this PR cc @mina86

[mina86]

https://github.com/near/nearcore/issues/7714

Also, the whole proof infrastructure is still work in progress so I’d argue it’s not that high priority.

[saketh-are]

I'll send a PR documenting tier1_network_info.

We also recently added network_routes (it was merged in https://github.com/near/nearcore/pull/9330 after this issue was created). I will document that one as well.

[bucanero]

On a side note, I think it would be super helpful for future docs, if we could auto-generate some OpenAPI reference out of the RPC node source code. Pagoda did that for the Enhanced API, and creating /updating docs could be done quickly with any tool that turns OpenAPI json/yaml files into documentation.

[telezhnaya]

@bucanero it's impossible, unfortunately, because OpenAPI does not support JSON RPC https://github.com/OAI/OpenAPI-Specification/issues/801

[bucanero]

Oh, I see, thanks for the feedback @telezhnaya .

I was reviewing a bit about JSON-RPC, and it seems a good option could be https://open-rpc.org/ . It's a fork of openApi, modified to accommodate JSON-RPC APIs.

Perhaps we can consider this as an alternative to find a way to auto-generate good docs for our node API

[telezhnaya]

I feel it's too raw and I'm not ready to invest much time. There's only one Rust crate I've found https://lib.rs/crates/openrpc, version 0.1.0 does not sound promising to me I think the best we can do here right now is just to suffer and wait, trying to document methods while we remember about it

[github-actions[bot]]

This issue has been automatically closed because it has been inactive for more than 180 days. Please reopen and prioritize this for development if it is essential.