YAML specification of RPC API

[carnesen]

Developers of RPC clients for Bitcoin Core would benefit from a machine-readable specification of the API. See for example #753 and references therein. Such a spec could also be used to generate html documentation programmatically for the calls à la Swagger instead of having to maintain that separately "by hand". Unfortunately Swagger itself is incompatible with JSON-RPC-style APIs, but it can provide us with inspiration. In particular, the format we use for the RPC specs could roughly follow the Swagger spec spec. Our specs should be written in YAML, which is more easily read and edited by humans than JSON. The schema/spec will describe the JSON types of the inputs and outputs (e.g. array, objects, number, string) as well as the Bitcoin-specific subtypes of the JSON scalars (e.g. "string : hash_t" where "hash_t" is a named type meaning "hex-encoded little-endian SHA256 hash" or whatever).

All told the RPC API involves more than a thousand individual fields. I got a good start on cataloging them already though last spring (https://github.com/carnesen/bitcoin-rpc-spec) and plan to continue this effort there now. Once I've completed the spec, I'll update this thread and start working on auto-generating html documentation from it for this site.

[harding]

Took a quick look, and this seems reasonable and should mesh with the information we already have which is in YAML format (converted into tables) but not yet well separated into data types.

[carnesen]

I still think this is a good idea, but I'm not actively working on it at this time. If I pick it back up, I'll reopen this issue.