Published on: 2015-02-17T18:46:17+00:00
Dario Teixeira, the primary author of Bitcoin.org JSON-RPC reference, has offered to help Dave by submitting a pull request against the docs adding the necessary type information for one RPC call. Dario suggests using OCaml-bitcoin API as a guide, which could be helpful even if someone doesn't use OCaml. To add the custom types defined in the API, they would need to add a new section to the docs, called List of Types, that lists all the custom types and their descriptions, indicating the JSON type used for serialization.In an email exchange, Dario Teixeira requested the primary author of Bitcoin.org JSON-RPC reference to provide type information in the API calls for better understanding. The author suggested submitting a pull request against the docs adding the type information needed for just one RPC call, which can later be generalized across all RPC docs. The author also provided easy editing options through GitHub and local checkout for the individual RPCs, and encouraged Dario to reach out in case of any questions or concerns.The author of OCaml-bitcoin library, Dario Teixeira, has requested Bitcoin developers to define more precisely the type information associated with each API call in the JSON-RPC reference. He believes that defining the precise set of types used in the RPC API and annotating the RPC calls in the source-code or in the API reference documentation would make writing bindings easier and less error-prone. It would also have the added advantage of better documenting the Bitcoin Core source-code itself. Teixeira acknowledges that it would not be necessary to extend this request to the deep data structures returned by some API calls. He assures that the bindings take a pragmatic stance of only processing the parameters and return results where a strong type discipline is imperative.The author has addressed a few questions raised on IRC, such as what does it matter if JSON only has a tiny set of types, why does it matter if the types are not even distinguished in the C++ source of Bitcoin Core, etc. Dario Teixeira concludes his letter by thanking the Bitcoin developers for their attention and all the work they put into Bitcoin development. He appreciates it and believes that it is not acknowledged often enough. The links to OCaml-bitcoin library, OCaml language description, Bitcoin developer reference and the type definitions created by the author have been provided in the original message.The author of OCaml-bitcoin, a library offering an OCaml interface to the official Bitcoin client API, has requested that Bitcoin developers define more precisely the type information associated with each API call in the JSON-RPC reference. This would make writing bindings easier and less prone to errors, as well as better documenting the Bitcoin Core source-code itself. The author has provided examples of the type definitions used in OCaml-bitcoin and notes that they have not been updated for Bitcoin Core 0.10 yet. The author also answered some questions raised on IRC regarding the importance of defining types, stating that deep down most programming errors are just type errors. The author concludes by thanking the Bitcoin developers for their work and expressing appreciation for their efforts.
Updated on: 2023-08-01T11:48:26.964953+00:00