Documentation of new market API

[vikramrajkumar]

From @theoreticalbts on February 16, 2016 2:44

According to @xeroc comment in cryptonomex/graphene#500 the API implemented in cryptonomex/graphene#500 cryptonomex/graphene#503 needs to be better documented. Discussion of that documentation effort should take place in this ticket.

Copied from original issue: cryptonomex/graphene#582

[vikramrajkumar]

From @mvandeberg on February 16, 2016 14:18

With regard to #500, the API is simply to open up methods from the fc crypto suite, which themselves are not documented. This was at the request of @bytemaster

With regard to #503, @xeroc, in what ways does the documentation need to be better? None of the methods are ground breaking from a market perspective, and the parameterization is consistent with the rest of the API with the exception of referencing assets by string instead of id, which was a primary motivation behind the new API calls.

[vikramrajkumar]

From @abitmore on February 16, 2016 15:43

Maybe just copy Polo's docs to docs.bitshares.org?

[vikramrajkumar]

From @abitmore on February 16, 2016 15:45

And what are the blog_post APIs? Why are they here?

[vikramrajkumar]

From @svk31 on February 16, 2016 15:51

While these are a good start it's a shame none of the "all markets" methods were implemented. We desperately need a way to poll for active markets and obtain some stats about them. Approximate equivalents of these two would have been great:

returnTicker: Returns the ticker for all markets
return24Volume: Returns the 24-hour volume for all markets, plus totals for primary currencies

[vikramrajkumar]

From @abitmore on February 16, 2016 15:52

@mvandeberg In regards to in-code documents, by a simple comparation of crypto api code to other APIs' code, anyone can see there are big differences.

[vikramrajkumar]

From @abitmore on February 16, 2016 15:57

@svk31 We simply have much much more markets than other exchanges, so a "all market" API is not practicable imo. However a "top X volume markets" API would be better.

[vikramrajkumar]

From @svk31 on February 16, 2016 16:1

Yea that's why I said approximate equivalent. Even just the top 10 by volume would be amazing, but of course the more the better...

[vikramrajkumar]

From @mvandeberg on February 16, 2016 17:7

@svk31 The market volume is being calculated every call. We are currently not saving that information in the database, so there is no quick way for sort on it and look up top 10 markets. That would require modification of how we store markets and orders and is beyond the scope of what I was asked to do.

[vikramrajkumar]

From @mvandeberg on February 16, 2016 17:12

@abitmore I am not sure what specific differences you are referring to. Of course the APIs are different, they are different APIs. The point of the crypto API was to expose cryptographic utility methods through the network layer for utilization by the web client. All of the implementation is in fc elliptic. Unfortunately there is no documentation on those methods and I was only given a list of methods to expose. I assumed they were commonly understood methods to anyone familiar with elliptic curve cryptography.

[vikramrajkumar]

From @abitmore on February 16, 2016 21:33

@mvandeberg thanks anyway.. I have no idea about these functions at all. Maybe it need to be done by others. @bytemaster @pmconrad? Thanks.

[vikramrajkumar]

From @pmconrad on February 16, 2016 22:9

Sorry, I didn't follow this discussion - can you provide a list? Which methods do you want to expose, which need documentation?

[vikramrajkumar]

From @abitmore on February 16, 2016 22:14

@pmconrad Please see https://github.com/cryptonomex/graphene/blob/fd09669be3ce017b038e341552552109595d3b0b/libraries/app/include/graphene/app/api.hpp#L199-L235 these are new added APIs without any document. Thanks for help.

[vikramrajkumar]

From @pmconrad on February 17, 2016 19:4

blind_sign and unblind_signature belong to this: https://bitsharestalk.org/index.php/topic,17315.msg220421.html#msg220421
I suppose these two shouldn't even be there - AFAIK they're not used anywhere in graphene currently, and if they are the API should include the blind_hash function as well.

I don't know anything about the range stuff nor the blind_factor stuff.

[abitmore]

I believe this has been done.