steemit
DP: META: Create an ideal Steem client specification
As a developer in any language I want a best set of features for a client interacting with the Steem blockchain. This includes how the application interface is constructed, and the functionality provided.
Using a car analogy
- application interface - automatic vs manual transmission, steering wheel-size, gull-wing doors or standard, digital dash or analog.
- functionality provided - 2 wheel drive or 4 wheel drive, the content of the information on the dash, electric motor or ICE.
AC
- [ ] comments from at least 6 developers from steemit or in the steem community describing, endorsing or rejecting features
- [ ] the DP contains a
.mdfile with the specification derived from all the comments. - [ ] the comment titled
# Collective Description - in progressshould be changed to# Collective Description - finaland include a link to the above.mdfile.
Endorsing: Metaprogramming
I feel like metaprogramming solves the problem of adding new methods to clients pretty effectiely, so I endorse this feature.
One feature of steem-ruby is to ask jsonrpc what api/methods are available from the node. Once it knows these facts, the developer can ask for an instance of a particular namespace, like FollowApi if follow_api is enabled on that node. All of the methods on follow_api become available.
As result, for any namespace that exists, the method can be invoked, without having to wait for steem-ruby development (me) to add that api/method.
Often, I would like to extend an api's functionality, so I go ahead and create a concrete class. I still don't add the methods, though. I let the exsiting method_missing callbacks do that. But for extra functionality, for instance, I want block_api to support json-rpc-batch for get_block, I created Steem::BlockApi and added a method named get_blocks that takes a range of block numbers.
Along these lines, one drawback to this is that operations are not enumerated by jsonrpc, so steem-ruby has no idea if a particular operation type is valid or not. It also has no idea if a particular operation type is virtual. I think it'd be nice if jsonrpc could list operations, but since it does not, I've opted to just let the node indicate if the operation is valid at broadcast.
Endorsing: Full Error Handlers
In steem-ruby, instead of returning result and error objects, it only ever returns result and raises an exception when it sees error. I parse the message to build up a meaningful error type.
The advantage of doing this is that retriable errors are more easily identifyiable and handled automatically.
The disadvanage is that any error message I haven't whitelisted will be instantiated as UnknownError.
Serialize transactions, manage keys, sign transactions, broadcast transactions, JSON RPC client + signing support
Something like this https://swagger.io/specification/ maybe that we can
- Generate documentation from code
- Verify/test code against specification
- Provide reference to generate clients from api (by version)
I'm proposing IDL to auto-generate serialization library for many different programming languages. Some library maintainer probably uses a bot to update their dependencies regularly. By having IDL (which can serve as a living specification), auto-generate it to many programming languages then publish it to many packages manager can improve the quality of existing Steem library out there while also open a door to have libraries for compiled languages (e.g Rust, C++, Golang).
IDL that I can think of which have support to wide ranges of programming languages is https://quicktype.io (well, it's more like auto-generator rather than IDL). Having your own IDL or meta-languages can also be good alternatives.
(though I really want to have GraphQL alongside with JSON-RPC as the secondary API, just like GitHub. But seems it's impossible for now to have it built-in in Steem 🙂)
