DP: META: Create an ideal Steem client specification

[relativityboy]

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 .md file with the specification derived from all the comments.
• [ ] the comment titled # Collective Description - in progress should be changed to # Collective Description - final and include a link to the above .md file.

[relativityboy]

Collective Description - in progress

[inertia186]

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.

[inertia186]

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.

[jnordberg]

Serialize transactions, manage keys, sign transactions, broadcast transactions, JSON RPC client + signing support

[jnordberg]

Interfaces should follow language/platform conventions

[r351574nc3]

Something like this https://swagger.io/specification/ maybe that we can

1. Generate documentation from code
2. Verify/test code against specification
3. Provide reference to generate clients from api (by version)

[DrSensor]

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 🙂)