API documentation #780 #1174

cogutvalera · 2018-07-25T09:19:26Z

PR for #780

oxarbitrage · 2018-07-25T13:14:50Z

nice job, ill take a look in more detail as soon as i can.

cogutvalera · 2018-07-25T13:16:29Z

Thank you very much ! Really appreciate all your efforts and help !

abitmore

Need to improve. Thanks anyway.

abitmore · 2018-07-25T14:56:13Z

libraries/app/include/graphene/app/api.hpp

+          * @param a Base in pair
+          * @param b Quote in pair
+          * @param limit Maximum number of orders to retrieve
+          * @return A list of orders with b:a pair


It returns history, not orders.

abitmore · 2018-07-25T14:56:34Z

libraries/app/include/graphene/app/api.hpp

+          * @param bucket_seconds Represents the length in seconds of bucket
+          * @param start Time in seconds from where buckets begin
+          * @param end Time in seconds where buckets stop
+          * @return A list of markets with b:a pair (maximum markets to retrieve is less than 200)


It returns history in one market, not markets. Descriptions of params seems off.

abitmore · 2018-07-25T14:59:01Z

libraries/app/include/graphene/app/api.hpp

+         /**
+          * @brief Get holders for a specific asset
+          * @param asset_id The specific asset
+          * @param start The start index of first asset


Seems wrong.

abitmore · 2018-07-25T15:00:17Z

libraries/app/include/graphene/app/api.hpp

+          * @param asset_id The specific asset
+          * @param start The start index of first asset
+          * @param limit Maximum limit must not exceed 100
+          * @return A holders for the specified asset


A holders sounds strange.

abitmore · 2018-07-25T15:01:27Z

libraries/app/include/graphene/app/api.hpp

+
+         /**
+          * @brief Get tracked buckets
+          * @return A list of tracked buckets


Perhaps need to explain what's a bucket.

cogutvalera · 2018-07-25T15:20:49Z

Thank you very much ! Will improve soon ! Sorry for mistakes !

cogutvalera · 2018-07-25T15:45:14Z

improved, but there still maybe some wrong explanations, I will check myself again and will improve/fix what will find wrong.Thank you very much !

…nd get_market_history

cogutvalera · 2018-07-31T05:21:06Z

improved and rebased already

pmconrad · 2018-07-31T14:06:25Z

libraries/app/include/graphene/app/api.hpp

+          * @brief Get range proof info
+          * @param proof List of characters
+          * @return A range proof info structure with exponent, mantissa, min and max values
+          */                                       


Do you understand how the crypto_api works?
Your documentation provides nothing useful that isn't obvious from the method/variable names.

not all details still researching this code in more details ... blind accounts and transactions are the main idea for crypto_api

cogutvalera · 2018-07-31T14:16:15Z

I will improve this documentation more soon ...

cogutvalera · 2018-09-02T05:01:18Z

Guys, thanks for your time and efforts ! Please check my new changes when you will have enough time for it. Should I make any other changes in api documentation or it is ok for now ?

Thanks !

pmconrad · 2018-09-05T15:34:58Z

libraries/app/include/graphene/app/api.hpp

@@ -343,8 +426,26 @@ namespace graphene { namespace app {
         asset_api(graphene::chain::database& db);
         ~asset_api();

+         /**
+          * @brief Get account holders for a specific asset


"account holders" doesn't make sense. Either "asset holders" or "accounts holding asset".

pmconrad · 2018-09-05T15:35:06Z

libraries/app/include/graphene/app/api.hpp

         vector<account_asset_balance> get_asset_holders( asset_id_type asset_id, uint32_t start, uint32_t limit  )const;
+
+         /**
+          * @brief Get account holders count for a specific asset


pmconrad · 2018-09-05T15:37:24Z

libraries/app/include/graphene/app/api.hpp

         vector<order_history_object> get_fill_order_history( asset_id_type a, asset_id_type b, uint32_t limit )const;
+
+         /**
+          * @brief Get markets with b:a pair


Gets accumulated market history, not current markets

pmconrad · 2018-09-05T15:39:12Z

libraries/app/include/graphene/app/api.hpp

+          * @param a Base in pair
+          * @param b Quote in pair
+          * @param limit Maximum number of orders to retrieve
+          * @return A history of orders with b:a pair, where a <= b, otherwise a and b will be swaped


If always a <= b then it doesn't make sense to call a "Base" and b "Quote". Backend is ignorant of UI market order.

pmconrad · 2018-09-05T15:39:36Z

libraries/app/include/graphene/app/api.hpp

+          * @param bucket_seconds Represents the length in seconds of bucket
+          * @param start Time in seconds from where buckets begin
+          * @param end Time in seconds where buckets stop
+          * @return A history in market with b:a pair (maximum markets to retrieve is less than 200), where a <= b, otherwise a and b will be swaped


…code convention

pmconrad · 2018-09-09T11:52:17Z

Your formatting changes seem to violate current conventions rather than improve things.

(Not that we're very consistent in that regard.)

cogutvalera · 2018-09-09T12:22:33Z

I have made that code formatting only for those lines which exceed 130 characters

pmconrad · 2018-09-11T16:38:24Z

Ok, keep your changes. Created #1318 for defining coding style.
@abitmore please re-review, I'm ok with the changes.

cogutvalera · 2018-09-11T16:39:44Z

Thanks !

abitmore

Note: I didn't check whether the docs about blinded transfers are correct because I know little about them.

abitmore · 2018-09-11T17:57:21Z

libraries/app/include/graphene/app/api.hpp

@@ -176,10 +184,34 @@ namespace graphene { namespace app {
                                                                        uint32_t stop = 0,
                                                                        unsigned limit = 100,
                                                                        uint32_t start = 0) const;
-
+         /**
+          * @brief Get history of orders with b:a pair


IMHO "history of orders" is not clear.

abitmore · 2018-09-11T17:58:55Z

libraries/app/include/graphene/app/api.hpp

+          * @brief Get history of orders with b:a pair
+          * @param a asset in pair
+          * @param b asset in pair
+          * @param limit Maximum number of orders to retrieve


I feel "number of orders" here is a bit weird.

abitmore · 2018-09-11T18:01:44Z

libraries/app/include/graphene/app/api.hpp

         vector<order_history_object> get_fill_order_history( asset_id_type a, asset_id_type b, uint32_t limit )const;
+
+         /**
+          * @brief Gets accumulated market history with b:a pair


I'm not sure if this description is appropriate, but I think we should at least mention OHLC. Actually, I think we can check other exchanges' API document and write ours accordingly.

abitmore · 2018-09-11T18:06:01Z

libraries/app/include/graphene/app/api.hpp

+          * @param a asset in pair
+          * @param b asset in pair
+          * @param bucket_seconds Represents the length in seconds of bucket
+          * @param start Time in seconds from where buckets begin


Why it's "Time in seconds"?

abitmore · 2018-09-11T18:07:21Z

libraries/app/include/graphene/app/api.hpp

+          * @param bucket_seconds Represents the length in seconds of bucket
+          * @param start Time in seconds from where buckets begin
+          * @param end Time in seconds where buckets stop
+          * @return A history in market with b:a pair (maximum markets to retrieve is less than 200), 


Why "maximum markets"?

abitmore · 2018-09-11T18:08:57Z

libraries/app/include/graphene/app/api.hpp

+          * @param start Time in seconds from where buckets begin
+          * @param end Time in seconds where buckets stop
+          * @return A history in market with b:a pair (maximum markets to retrieve is less than 200), 
+          * where a <= b, otherwise a and b will be swaped


IMHO mentioning the swap here doesn't make sense.

abitmore · 2018-09-11T18:09:41Z

libraries/app/include/graphene/app/api.hpp

+          * @brief Gets accumulated market history with b:a pair
+          * @param a asset in pair
+          * @param b asset in pair
+          * @param bucket_seconds Represents the length in seconds of bucket


I don't know whether "bucket" is the most commonly used word for this purpose, although it's in our code.

abitmore · 2018-09-11T18:13:46Z

libraries/app/include/graphene/app/api.hpp

+         /**
+          * @brief Get tracked buckets.
+          * Track market history by grouping orders into buckets of equal size measured in seconds 
+          * specified as a JSON array of numbers.


This description starts with a verb, thus IMHO is not appropriate for this API. It seems it's copied from the plugin startup options.

abitmore · 2018-09-11T18:15:25Z

libraries/app/include/graphene/app/api.hpp

+         /**
+          * @brief Generates a pedersen commitment: *commit = blind * G + value * G2. 
+          * The commitment is 33 bytes, the blinding factor is 32 bytes.
+          * (For more information about pederson commitment check please next url 


"check please" -> "please check"?

abitmore · 2018-09-11T18:20:58Z

libraries/app/include/graphene/app/api.hpp

+          * a "range proof" must be supplied to prove that none of the outputs commit to a negative value.
+          * The range proofs are computed by library functions in secp256k1-zkp, 
+          * which provides a very flexible and capable range proof library, 
+          * in which a balance can be struck between amount of privacy and compactness of proof.


I guess this is more a main description rather than a "brief", because it's long. In the meanwhile there is no main description section here.

abitmore · 2018-09-12T15:50:14Z

libraries/app/include/graphene/app/api.hpp

@@ -185,11 +185,11 @@ namespace graphene { namespace app {
                                                                        unsigned limit = 100,
                                                                        uint32_t start = 0) const;
         /**
-          * @brief Get list of orders with b:a pair
+          * @brief Get asset pairs with b:a pair


"asset pairs" doesn't make sense. Please talk to traders to see what should be put here.

OK. Sure. Thanks !

cogutvalera · 2018-09-14T04:08:08Z

Jacob Walrus, [14.09.18 06:23]
[In reply to Valera Cogut]
"Fill order history" would probably sound better and be more obvious to the layperson what you are talking about if you simply used "market history". "Asset pairs" is pretty good as is but "trading pairs" might be better. "Order book" would make most sense to traders I think over "list of orders". Did that help answer your questions?

cogutvalera · 2018-09-14T04:21:19Z

should I use "market history" instead of "asset pairs" ? or "trading pairs" ? or "order book" ?
Guys suggest please what do you think is more better suited for next API call in your opinion.

         /**
          * @brief Get asset pairs with b:a pair
          * @param a asset in pair
          * @param b asset in pair
          * @param limit Maximum count of asset pairs to retrieve
          * @return Asset pairs with b:a pair
          */
         vector<order_history_object> get_fill_order_history( asset_id_type a, asset_id_type b, uint32_t limit )const;

Thanks !

cogutvalera · 2018-09-14T04:28:45Z

IMHO for me as I understood correctly from Jacob Warlus answer the most makes sense here "market history"

abitmore · 2018-09-14T09:06:24Z

@cogutvalera apparently you've learnt some. Please talk more with your friend.

abitmore · 2018-09-14T08:50:12Z

libraries/app/include/graphene/app/api.hpp

         vector<bucket_object> get_market_history( asset_id_type a, asset_id_type b, uint32_t bucket_seconds,
                                                   fc::time_point_sec start, fc::time_point_sec end )const;
+
+         /**
+          * @brief Get list of seconds for grouping asset pairs in OHLC https://en.wikipedia.org/wiki/Open-high-low-close_chart


"asset pairs" is not suitable here.

In addition, should tell the user where did this list come from.

abitmore · 2018-09-14T08:51:41Z

libraries/app/include/graphene/app/api.hpp

+          * Thus supporting OHLC https://www.investopedia.com/terms/o/ohlcchart.asp
+          * @param a asset in pair
+          * @param b asset in pair
+          * @param bucket_seconds Represents the length in seconds of bucket


Please note that bucket_seconds here need to be within result of get_market_history_buckets() API, otherwise no data will be returned.

abitmore · 2018-09-14T08:57:02Z

libraries/app/include/graphene/app/api.hpp

+          * @param b asset in pair
+          * @param bucket_seconds Represents the length in seconds of bucket
+          * @param start Time point in seconds from where buckets begin, E.G. "2018-09-12T18:00:00"
+          * @param end Time point in seconds where buckets stop, E.G. "2018-09-12T18:00:55"


I think your example here is a bit misleading or confusing. The difference of them is 55 seconds. What will return if the bucket_seconds passed in is greater than 55 seconds, for example, 1 day? Does start or end need to be "divisible" by bucket_seconds?

IMHO, a better example would be in the main description section, but not after individual parameters, because valid data range of parameters are affected by each other. In short, use most common scenario or most common input data set to make example.

abitmore · 2018-09-14T09:05:31Z

libraries/app/include/graphene/app/api.hpp

+
+         /**
+          * @brief Get accumulated market history with b:a pair
+          * Thus supporting OHLC https://www.investopedia.com/terms/o/ohlcchart.asp


IMHO the link is not needed here. Traders know what's OHLC.

abitmore · 2018-09-17T14:59:17Z

libraries/app/include/graphene/app/api.hpp

@@ -185,30 +185,31 @@ namespace graphene { namespace app {
                                                                        unsigned limit = 100,
                                                                        uint32_t start = 0) const;
         /**
-          * @brief Get asset pairs with b:a pair
+          * @brief Get order book with b:a pair


Absolutely wrong.

What is better in your opinion ? Because trader told me this variant with "order book" is better, but it isn't. Can you please assist me just a bit ?

Thanks !

An API querying for history won't return an order book, that's why.
Please try understand the API, then explain it to the trader and get feedback. Modifying code cluelessly is a waste of time.

Sure I can give my opinion or even write the document by myself, however, since you asked to work on this issue, you should try to get it done by yourself.

I've changed "order book" to "trading orders" in my last commit 1 day ago, is it wrong ?

IMHO, "trading order" is a confusing phrase. Why not ask traders?

after our discussion and a lot of efforts trying to figure out the best suitable solution with @abitmore about API doc, fill_order_operation and after my code researches I've some results for your judgement:

"matching orders" can be filled partially, so traders will be confused with such API doc description (@abitmore helped me here with more details & examples, thanks a lot !)

this API method get_fill_order_history will return filled orders which also are confirmed by blockchain, IMHO the best solution is to use "confirmed orders", thus traders will understand completely what will be returned to them.

Thanks !

I don't think "confirmed orders" is good enough.

IMHO perhaps next:

just simply "filled orders"

or combination "filled and confirmed orders"

2nd version is more accurate and descriptive IMHO

"filled orders" are very similar to "matched orders", and I've said why it's not good use them as is (note: I didn't say they can't be used in a sentence that's clearer). "confirmed" is very confusing. "filled and confirmed" doesn't make sense IMHO.

Can you reword the whole sentence? It's not only about choosing a noun or a phrase, it's the whole sentence that should be clearer. If unable to clearly describe it in 6 words or one sentence, please use more words and more sentences.

ok, understood, sure. Thanks !

abitmore · 2018-09-17T15:01:13Z

libraries/app/include/graphene/app/api.hpp

          * @return A history in market with b:a pair (limit to retrieve is less than 200 buckets)
          */
         vector<bucket_object> get_market_history( asset_id_type a, asset_id_type b, uint32_t bucket_seconds,
                                                   fc::time_point_sec start, fc::time_point_sec end )const;

         /**
-          * @brief Get list of seconds for grouping asset pairs in OHLC https://en.wikipedia.org/wiki/Open-high-low-close_chart
-          * @return A list of seconds which are represented as unsigned integers
+          * @brief Get list of seconds for grouping a book's orders in OHLC


Wrong as well.

cogutvalera · 2018-09-20T20:47:37Z

just for the info: pushed new commit "fixed: (trading orders) -> (matching orders)"

…ets methods

cogutvalera · 2018-10-05T13:45:25Z

changed last commit's message

abitmore · 2018-10-05T23:41:48Z

I give up. @cogutvalera I think it's better to update the docs about orders as follows (please wrap long lines):

         /**
          * @brief Get details of order executions occurred most recently in a trading pair
          * @param a One asset in a trading pair
          * @param b The other asset in the trading pair
          * @param limit Maximum records to return
          * @return a list of order_history objects, in "most recent first" order
          */
         vector<order_history_object> get_fill_order_history( asset_id_type a, asset_id_type b, uint32_t limit )const;

         /**
          * @brief Get OHLCV data of a trading pair in a time range
          * @param a One asset in a trading pair
          * @param b The other asset in the trading pair
          * @param bucket_seconds Length of each time bucket in seconds. Note: it need to be within result of get_market_history_buckets() API, otherwise no data will be returned
          * @param start The start of a time range, E.G. "2018-01-01T00:00:00"
          * @param end The end of the time range
          * @return A list of OHLCV data, in "least recent first" order. If there are more than 200 records in the specified time range, the first 200 records will be returned.
          */
         vector<bucket_object> get_market_history( asset_id_type a, asset_id_type b, uint32_t bucket_seconds,
                                                   fc::time_point_sec start, fc::time_point_sec end )const;

         /**
          * @brief Get OHLCV time bucket lengths supported (configured) by this API server
          * @return A list of time bucket lengths in seconds. E.G. if the result contains a number "300", it means this API server supports OHLCV data aggregated in 5-minute buckets.
          */                                          
         flat_set<uint32_t> get_market_history_buckets()const;

References:

@abitmore

…ry and get_market_history_buckets methods (Thanks @abitmore)

cogutvalera · 2018-10-06T05:32:14Z

@abitmore Thanks ! Changes are done.

cogutvalera · 2018-10-06T10:45:56Z

Thanks !

abitmore requested changes Jul 25, 2018

View reviewed changes

abitmore added this to the 201810 - Non-Consensus-Changing Release milestone Jul 29, 2018

nanomobile and others added 4 commits July 31, 2018 08:19

API documentation bitshares#780

fa6078a

add API documentation for get_asset_holders method

f4ff81c

improved descriptions

ec69293

add description about swap quote and base in get_fill_order_history a…

e11e75a

…nd get_market_history

cogutvalera force-pushed the valera_issue_780 branch from 5fef044 to e11e75a Compare July 31, 2018 05:20

pmconrad reviewed Jul 31, 2018

View reviewed changes

improved crypto api documentation

d6204e0

pmconrad reviewed Sep 5, 2018

View reviewed changes

improved some words in api descriptions and made some formatting for …

8ac5a96

…code convention

abitmore reviewed Sep 11, 2018

View reviewed changes

improved API code documentation

2b9d43f

cogutvalera added 2 commits September 12, 2018 17:35

improved API documentation for buckets and orders

eba8f2f

small improvement

7d914cf

abitmore reviewed Sep 12, 2018

View reviewed changes

abitmore assigned cogutvalera Sep 14, 2018

abitmore reviewed Sep 14, 2018

View reviewed changes

cogutvalera added 2 commits September 17, 2018 09:36

improved API documentation about order book

dc0b863

little improvement

686b075

abitmore reviewed Sep 17, 2018

View reviewed changes

cogutvalera added 2 commits September 18, 2018 15:00

fixed: (order book) -> (trading orders)

b1d67ef

fixed: (trading orders) -> (matching orders)

53b11e4

Improved API doc for get_fill_order_history & get_market_history_buck…

c6f603e

…ets methods

cogutvalera force-pushed the valera_issue_780 branch from 0a49cfc to c6f603e Compare October 5, 2018 13:44

Improved in-code API doc for get_fill_order_history, get_market_histo…

ffc842a

…ry and get_market_history_buckets methods (Thanks @abitmore)

abitmore approved these changes Oct 6, 2018

View reviewed changes

abitmore merged commit 85496e7 into bitshares:develop Oct 6, 2018

cogutvalera mentioned this pull request Oct 6, 2018

API documentation #780

Closed

8 tasks

TheTaconator mentioned this pull request Oct 15, 2018

Release Notes for BitShares Core 201810 #1381

Closed

API documentation #780 #1174

API documentation #780 #1174

Conversation

cogutvalera commented Jul 25, 2018

oxarbitrage commented Jul 25, 2018

cogutvalera commented Jul 25, 2018

abitmore left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cogutvalera commented Jul 25, 2018

cogutvalera commented Jul 25, 2018

cogutvalera commented Jul 31, 2018

Choose a reason for hiding this comment

cogutvalera Jul 31, 2018 • edited Loading

Choose a reason for hiding this comment

cogutvalera commented Jul 31, 2018

cogutvalera commented Sep 2, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pmconrad commented Sep 9, 2018

cogutvalera commented Sep 9, 2018

pmconrad commented Sep 11, 2018

cogutvalera commented Sep 11, 2018

abitmore left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cogutvalera commented Sep 14, 2018

cogutvalera commented Sep 14, 2018

cogutvalera commented Sep 14, 2018

abitmore commented Sep 14, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cogutvalera Sep 19, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cogutvalera Sep 23, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cogutvalera commented Sep 20, 2018

cogutvalera commented Oct 5, 2018

abitmore commented Oct 5, 2018

cogutvalera commented Oct 6, 2018

cogutvalera commented Oct 6, 2018

cogutvalera Jul 31, 2018 •

edited

Loading

cogutvalera Sep 19, 2018 •

edited

Loading

cogutvalera Sep 23, 2018 •

edited

Loading