Better API - Please Help Define It

[theoretical]

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.

[theoretical]

I'd like to allow plugins to define API calls, and configuration file options to specify which plugins to enable, and which plugins require login to access their API calls.

• It allows us to break the API up into smaller units.  Currently database_api is huge because we have to put everything accessible without login in there.
• It allows a path for API upgrade.  If the old API and new API are plugins which can be enabled / disabled by a specific site, then a site can upgrade the API on their schedule, not ours.
• It allows different security profiles.  For example, we could create a "HTTP plugin" which makes login and secure API calls of other plugins accessible over HTTP.  Sites that want to interface with the wallet over HTTP can use that plugin (and then it is on them to ensure the wallet is properly firewalled, containerised or otherwise isolated), while the default config has the plugin disabled for security reasons.

Related issues:  #245, #246, #422.

[TravelsAsia]

I'm not sure if this is an API improvement or something that is already there but not accessible from the wallet. It would be nice to make cold storage simple.

[wackou]

pull request here: https://github.com/cryptonomex/graphene/pull/462

[monsterer]

Oh yes - another point:

*) 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.

[wackou]

There's this also:

https://github.com/cryptonomex/graphene/issues/339

I am actually going to submit a pull request for it (hopefully tonight) for the first 3 ones.

The last one (blockchain_get_witness_slot_records) required some sort of optional indexing in bts1, and I'm not sure it is implemented in graphene. A workaround (for me) would be to allow to query blocks in batch, as suggested by roadscape, and/or have a way to know which block was produced/missed by a witness.

[roadscape]

 - get_market_history via RPC & in the CLI wallet appears to return the first 200 buckets, not the most recent 200 buckets.

 - Consistency in returning object ids from the API - tx's, ops, accounts, etc. Ideally whenever an object is returned, its id is included.

 - More/bigger batch methods. Until the API is more fleshed out, simply making it easier to pull data in bulk from witness_node can really help fill in the gaps. e.g.:
   - get_account_history - ideally could return more than 100 items
   - get_full_blocks(start, limit) - would be nice to have this. blocks can only be pulled 1 at a time

 - Returning virtual ops where expected (get_block?). Many virtual ops are only seen in get_account_history, and never show up in get_block

 - Governance features: important for this data to be as rich as possible.. for example, the ability to query how much a worker has been paid *in total*. Currently we can only pull the "un-withdrawn" balance object.

 - Would be nice if proposals were not removed from the db, until we get the plugin architecture for this stuff. And to be able to see if a proposal was in actually approved or not, after the fact.

I could come up with a lot of "nice-to-haves" but in the short term just exposing as much data as possible helps a lot.

[xeroc]

Another list of feature requests:
https://github.com/cryptonomex/graphene/issues/382

Thanks for considering to improve the API!!!

[lil_jay890]

Basically what we need is to be able to access the wallet from a 3rd trading platform.

1.  Need to receive "tick" data (this is the last reported price and volume for an asset).  We need to take these "ticks" and create price charts with them.
2.  Need to be able to access the exchange from the 3rd party platform.  This includes account data such as open positions balances.
3.  The platform needs to be able to create and send orders to the DEX on behalf of the user.  The dex needs to be able to take this command and execute the order.  The dex will need to be able to accommodate limit and stop orders on the block chain level.

[TravelsAsia]

The ability to automatically return funds if a minimum amount isn't reached. Think Kickstarter.

[Xeldal]

Any time a balance or amount is returned it should be a consistent format (instead of sometimes strings sometimes integers)

Any time a balance or amount is returned it should be adjusted to the proper precision or the precision should be included(so multiple calls are not required)

When returning an order book, i'd like to see it separated in to an array of "bids": and an array of "asks": ideally ordered most to least relevant (standard for exchanges)

like monsterer mentioned access to all commands via http.  I believe its currently still not possible to cancel an order this way.

having a separate call for placing a bid and placing an ask that accepts the standard fields "price" and "amount" instead of the current "amount" and "minimum amount expected"  (it works just fine and makes sense as it is with just 1 call but its not the standard way of doing it.)

in the return from get balances, it would be nice to have for each asset an "amount_in_orders" value

with the exception of access to cancel_order and other http requests, all the above have work arounds, just suggesting for simplicity and similarity to other exchanges.

[monsterer]

HTTP access to all parts.

Exchanges need these functions:

* GetBlockHeight
* ListSinceBlock - especially important, to avoid jump through hoops as we do now
* GetBalance
* Send

Every transaction sending function should return a TXID immediately, which is then visible whenever that transaction turns up in future - and transaction must be queryable using this TXID at any time.

[bytemaster]

Everyone who wants a better API, please give us detailed description of what you want the API to be.