rebolek/Bibox.md

## Bibox.md

      
    Raw
  

              Bibox.md
            
          
    Bibox API

This document focuses on evaluating Bibox API from the client implementation point of view. The implementation was done using documentation available at GitHub.
HTTP headers

While the documentation sufficiently describes the API calls, it's not enough when implementing the API client from scratch. Bibox server expects specific set of HTTP header, however, these requirements are not specified anywhere and have to be found by trial and error. Without them, HTTP status 500 - Internal server error is returned. When only some of the headers are provided, HTTP status changes to 200 and Bibox error "3000 - 请求参数错误" is returned. Here's the list of required HTTP headers:
origin: {https://www.bibox.com}
referer: {https://www.bibox.com/}
user-agent: {Mozilla/5.0 (X11; Linux i686)}
accept: "application/json"
Content-Type: "application/json; charset=UTF-8"
Error handling

As described above, when some of the headers are missing, HTTP status 500 - Internal server error is returned. This HTTP status should be reserved only for serious problem with the server code, missing headers should be handled on server side and more appropriate status like 403 should be returned, or Bibox error like 3000 described above.
The error message is in Chinese, which may be less than optimal for non-Chinese reader, which leads us to following two points:

Where is the list of error codes with some description? Number 3000 and some short text in Chinese is not very descriptive.
For example Coinbase offers localization for error messages. It would be nice to have something like that for Bibox.

With list of error codes and/or support for localization of error codes, handling API errors would be much easier.
Naming inconsistencies

While the API is fine in its current incarnation, when working on new version, naming consistency should be considered. Consistency in naming leads to easy to understand code, that takes less time to read and write. Here are some examples of small inconsistencies that do not limit functionality, but do not help with readability:

For getting deposit and withdrawal addresses there are commands "transfer/transferIn" and "transfer/transferOutInfo". Both commands should or should not have the Info suffix.
There's inconsistency in returned value names. "transfer/coinList" returns e.g. symbol, while "transfer/assets" returns coin_symbol etc.
Some calls require coin symbol, while others require coin ID.
Some names use CamelCase naming scheme, while others use underscore to separate words. It would be better to be consistent and choose one naming scheme.
Inconsistent indexing. Some lists are zero-based, some are one-based. See this example for opening an order:

  account_type,   //account type，0-regular account，1-margin account
  order_type,     //order type，1-market order，2-limit order
  order_side,     //order side，1-bid，2-ask
  pay_bix,        //whether using bix for transaction fee，0-no，1-yes


Some calls return time, other timestamp

This list is not complete and other examples of small inconsistencies can be found.
Other questions


what is money argument in "orderpending/trade" command? Opening an order works when it's set to zero.
There's pair, coin_symbol and currency_symbol in "orderpending/pendingList" and "orderpending/pendingHistoryList" commands. What's the exact relation between them? Also, what's the difference between these two commands?

Conclusion

While the missing documentation for required HTTP headers can be serious showstopper for Bibox client implementation, fixing various naming inconsistencies and improving documentation for current API functions is not so serious problem. However it could lead to an API that is easier to use.