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
RFC: Formal description of the RPC API #29912
Comments
Don't we have plethora of well documented guides and specifications on the JSON-RPC api ? https://developer.bitcoin.org/reference/rpc/ https://en.bitcoin.it/wiki/API_reference_%28JSON-RPC%29 Considering your need for a state-of-the-art framework / wrapper, you can always find a suitable project on Github, But it might be interesting to maintain a cross-language suite under the bitcoin core account authority |
No. I'd highly doubt that there is a better source of the documentation and specification than Bitcoin Core itself. (If there is, then that is a bug in Bitcoin Core, which should be fixed) This example has many issues:
This is the same as above, just rendered differently.
I am aware of the file, because I initially wrote it. It describes the concept of the interface, but it is not a specification. This is a wiki page that lists some manually maintained software projects, so all of them have the issues I mentioned in the original post. I don't have the time right now to list all the bugs they have, but if you spend enough time you will find that they are either not a specification, or that they are unmaintained for years, or that they have implementation errors. Edit: If there is a single software project out there, which currently correctly and fully implements the RPC API in a type-safe manner, it would be interesting to see how they approached it. But I doubt there is one? |
Note that automatically generated RPC docs are also available for each major version at https://bitcoincore.org/en/doc/ |
Yes, I am aware. They are based on the |
I vaguely recall an issue or discussion around machine-readable API specs in the past, but I cannot find it. I believe @laanwj commented on it. |
I think this is an interesting approach to consider. I'm quite fond of OpenAPI but I'm not sure how well it would lend itself to a JSON-RPC, but perhaps it works well enough? There is a sibling project specifically focused on JSON-RPC (https://open-rpc.org/ ) but it has less tooling and support. Would be cool if this means we could be spec-driven, build a tool that generates (server) header files from the spec so the RPC method implementations have compile time checks on parameters and responses etc. |
I must have failed to understand your question, my apology 🧐 If that so, I could be interesting to build something with OpenRPC close to OpenAPI https://open-rpc.org/ With a little bit of tweaking, we might also be able to use the Swagger UI originaly for REST API https://petstore.swagger.io/ |
Much of it is already there, just not exposed. The The same data that's used for rendering help could be returned on the RPC in a raw, machine-readable structured format. Easiest would be to define our own format, but if there is a suitable standard format that will work for JSON-RPC that's of course preferable. I don't think there was at the time I looked into it, but who knows. |
Concept ACK. IMHO, a formal specification (especially machine ingestible) would add value for downstream clients. There is some great info/guidance in Maybe it's just a matter of adding content to the RPC interface guidelines section of the developer notes, but I think there is value in defining the approach that should be taken by PR authors proposing RPC changes. For example, covering:
|
Currently (all?) clients manually implement the RPC API, which is problematic, because:
So it could make sense to have a formal specification.
Please leave a comment if there are additional aspects to consider here, or if you have ideas for a solution.
One solution for a formal description could be OpenAPI. Generators exist, such as (random example) https://github.com/microsoft/kiota?tab=readme-ov-file#supported-languages
The text was updated successfully, but these errors were encountered: