Unfortunately, the feedback is not helpful. I want specific requests INPUT ARGUMENTS and RETURN VALUES.
The API already allows you to do everything or can easily be wrapped in one that can. Examples are help, vague descriptions are not.
You must be kidding! theoretical's feedback is solid and very useful. It helps for making the API consistent and far easier to learn. It is simply a matter of providing a more standardized format for parameters and return values. With a little thought the API can be structured FAR better than it is. I've seen plenty of API's for lots of applications in my time (like performance critical CAD APIs for circuit representation for example) but quality DOES take time. From what I see everybody is always in such a big rush, skipping standard engineering practices (like UI mockups and use case testing with real users), and we can see the results of that approach.
I also think the new API should have a single object type for input and output, and do input parsing and output annotation by reflection.
For example:
- On the input side, we want API to accept an asset name wherever we accept an asset ID.
- On the output side, whenever an asset is returned by API, we return a 3-field object of the form {"sym" : symbol, "prec" : precision, "amount" : x}
We currently accomplish this by requiring each asset method to take asset as a string and then manually call parsing functions. Which is done inconsistently.
A better approach is to have every API call take an input struct, then use reflection to find any (potentially deeply nested) JSON fragment of the incoming object which has an asset_id_type, essentially moving the responsibility to parse asset ID's from the API method to the API framework (where "API framework" means some new, Graphene-specific glue code, as it will have to be aware of chain_db).
Likewise, output annotation requirements like the second requirement above can be handled similarly: Any place the output object has an asset_id_type, the framework automatically annotates it with the name and precision of the asset. Or possibly instead fills in a secondary "asset LUT" in the response containing such information for all assets (which makes the response smaller).
Accounts could obviously similarly benefit.
Not sure about the level of standardization possible, or the use of reflection (that has a negative performance impact), but looking at the CLI wallet API tells me no attempt was made to group similar calls based on input or output parameters. I doubt it's feasible to have a single input or output structure, but I do believe it could be improved from the plethora of variants I see.
Make a single point of entry into the system for API calls, rather than having the API commands duplicated (but with different functionality) between the cli_wallet and the witness_node.
I think what needs to happen is that API calls need to be automatically forwarded from the cli_wallet to the witness_node.
This ties into my previous points, it's better if we have ways to refer to API methods, or groups of API methods, in a config file, so we'd be able to configure enabling/disabling this forwarding on a per-call or per-API basis. And if the cli_wallet can ask the witness_node for type information on all API methods it supports, then it can improve the forwarding, even if the cli_wallet is not implemented in the same language as the backend.
Which leads me to the next item on my wishlist, writing a cli_wallet in Python so you can use proper scripting instead of the very clunky transaction_builder for creating proposed transactions, but that's sort-of off-topic. There's a lot I'd want to do to improve Graphene -- doing it all would probably take a year or two and several junior devs.
I don't see any reason that can't be done, though it would need to be evaluated for it's impact on performance.
Also on my wishlist for the API: Generate a JSON blob representing full type information for each API call, which can be used to auto-generate language bindings for the API.
You can think of this as like splitting James's JSON operation serializer into a frontend which reflects all Graphene types, and a backend which outputs various useful JS code, such as a JS class for all C++ structs. The frontend would then output a JSON blob which is taken by the backend.
I'm pretty sure JS language object model is sufficiently powerful that the backend could be completely written in JS as a generic library, which would take the JSON blob and construct the classes at runtime. Python could be done similarly.
This is the best piece of feedback theoretical provided. Not only will this improve the API, it will also improve it's adoption by eliminating language barriers. I've been programming in JScript since it was invented back in the 90s, using it to build database driven web aps
on the server when everybody else was using cold fusion or Visual Basic (yuk!). JScript (ECMA or Javascript, basically all the same) is a robust, touring complete and object oriented scripting language efficient and adequate for just about any task a script language is suitable for. Witness just how versatile JSON is. It is a concise, easy to read, highly malleable interface notation that has replaced other contenders like XML and YAML for many uses.
I find the CLI API cumbersome, difficult to learn and not very well engineered.
About a month ago I did a bit of research on the pros and cons of angular vs. react-js, and learned that node.js is a package manager for javascript code. I like the improvements react-js has made over angular, it really helps the code readability a lot as well as making it easier to write UI code. It looked like a natural fit and helps to overcome limitations of CSS, for one thing extending procedural functionality to the declarative only CSS space. I was a bit skeptical of making all CSS inline references, but I see the benefits of that with react.