Refactor API calls to be more future-proof

[theoreticalbts]

Implementation of #236 has revealed a general issue when extending API calls. When adding parameters to an API call, it has been noted that we should have a cycle of introducing a new call, deprecating the old call, waiting for web UI code to be updated, and then removing the old call.

The deprecation cycle is necessary because adding parameters to an API call breaks every API client that uses that call, even if the new parameters have default values, because the FC reflection API does not understand how to interact with default values due to underlying deficiencies in C++

In this ticket, I propose a solution to this problem: Most or all API calls should be rewritten to take a single struct, containing the values that were previously passed as separate arguments. Defaults can then be placed in the C++ struct definition, and if some fields do not occur in the JSON dictionary provided by the client, then those fields should not be assigned by the API framework and thus will have their default values.

I should test that the API framework does in fact give fields that do not exist in the JSON object their default values.

[theoreticalbts]

We could even implement this API entirely in C++ without breaking clients that use positional arguments. Here's how I'd do it:

• Create a new API method macro called e.g. FC_EXTAPI
• FC_EXTAPI has the following semantics:
• If a single JSON object is passed, then the method is called directly with the object. Fields that exist in the C++ struct but not in the JSON object should never be assigned by the API framework, and thus will take their default values as specified in the C++ struct definition.
• If a single JSON value of a non-object type is passed, or a number of JSON entities other than 1 is passed, then the struct fields are filled in order with the provided values. If the provided values are fewer than the number of struct fields, then the remaining fields should not be assigned by the API framework, and thus will take their default values as specified in the C++ struct definition.

By straightforwardly defining parameter structs, we can replace FC_API methods with FC_EXTAPI methods, while maintaining complete backward compatibility from the client's point of view.

The win here is that, by maintaining support for positional arguments, the transition from brittle argument-based methods to extensible struct-based methods can occur without breaking client code.

[theoreticalbts]

This should wait until #422 .

[vikramrajkumar]

This issue was moved to bitshares/bitshares-core#64