Skip to content

Add API annotations for swagger

General note: hafbe API contains a number of "generally useful" methods that don't require any data from hafbe tables or indexes (other than hardcoded tables like operation type info that don't require a replay) . In such cases, we should probably move these functions to hafah (hafah requires no replay). I've marked the likely candidates for such a move.

  • 1. If possible, change from set-of-keys/key-content to more powerful filtering allowing matching on multiple key-contents and new syntax for those as I proposed in chat: use a syntax like path-filter="value.creator=steem" and allow multiple path-filters to be specified in the URL, then use a rewrite rule to get it into a form acceptable to postgrest. e.g &path-filter="value.creator=steem"&path-filter="value.new_account_name=kefadex"). This impacts /blocks/{block-num}/operations and /block-numbers now and possibly other future API calls, and I think my proposed syntax is much friendlier and more powerful, so we should decide on this issue soon.

We need to rename several functions to avoid overlap with hafah and also to make their functionality clearer:

  • 2. OLD /blocks: RENAME /block-operation-counts - Specifies number of blocks to return starting with head block, defaults to 20 Response is operation counts for each block (i.e. referred to as block stats in docs). This doesn't have opname/virtual (which seems correct).

  • 3. OLD /blocks/{block-num}/operations/types RENAME /block-operation-counts/{block-num} returns operation counts for a given block-num.

  • 4. FUNCTION CHANGE for /block-operation-counts/{block-num}: drop opname/virtual fields from response. This will make its response match above method (and also the response of get_op_count_in_block currently used by hafbe_ui itself).

  • 5. /blocks/{block-num} This is a near duplicate of hafah/blocks/{block-num}. It inconsistently adds \\x in front of witness signature, transaction ids, and block_ids (but not to regular signatures). PROBABLY SHOULD ELIMINATE FROM HAFBE, USE HAFAH CALL WHEN THIS DATA NEEDED AND LET APP DO ITS OWN PREFIXING.

  • 6. OLD /blocks/{block-num}/header POSSIBLE NEW NAME: /blocks/{block-num}/global-state returns block headers + dgpo-like info (DANTODO: need to describe better for docs). ANOTHER OPTION FOR NAME: /global-state/{block-num} (my current preference is for this name).

  • DANTODO: /blocks/{block-num}/operations filters by list operation-type-ids, account_name(null), paging, set-of-keys, key-content, data-size-limit (PROBABLY NEED TO RENAME TO DIFFER FROM HAF, STILL NEEDS THINKING)

These are all fine as they are:

/block-numbers - List the block numbers that match given optype/set-of-keys filter, account name and time/block range in specified order
/block-numbers/headblock returns last block number in HAF database
/block-numbers/headblock/hafbe returns last block number synched by the block explorer
/block-numbers/by-creation-date/{timestamp} returns last created block number for given date

  • 7. /transactions/{transaction-id} returns hafbe_types.transaction. REPLACE hafah's /transactions with hafbe's and eliminate hafbe's. Rremove age field to avoid caching issues. In practice, this means we have a call that groups transaction json vs metadata and a timestamp looked up from the block that holds the transaction.

  • 7. OLD /operation, NEW /operation-types/

  • /operations/types lookup optype ids for operations matching a partial operation name (THIS SHOULD BE MOVED TO HAFAH I THINK)

  • /operations/types/{type-id}/keys returns json body keys for an operation type (THIS SHOULD BE MOVED TO HAFAH I THINK)

  • 8. OLD /operations/body{operation-id} NEW /operations/{operation-id} lookup an operation using its operation-id

  • Maybe rename seq to oppos if it is same thing in docs. Example return value is wrong (extra brackets).

  • Remove age field.

  • Four different ways to know it is virtual (trx_in_block, trx_id, op_type_id, and is_virtual fields). Do we really need them all?
  • What does is_modified mean: It means some part of operation has been removed. We need a better name and probably a better way of making the operation smaller.
  • (THIS SHOULD BE MOVED TO HAFAH I THINK)

Ok AS-IS:

/accounts/{account-name} Get information about account's balances and parameters
/accounts/{account-name}/authority Get information about account's OWNER, ACTIVE, POSTING, memo and signing authorities
  • /accounts/{account-name}/operations List the operations in the reversed order (first page is the oldest) for given account. The page size determines the number of operations per page. Filters by list of operation type ids.
  • Remove age.
  • Decided what to do about is_modified here too.
  • (THIS SHOULD BE MOVED TO HAFAH I THINK) Should we keep old hafah version of this as legacy or not?

/accounts/{account-name}/operations/types lists all types of operations that the account has performed since its creation

  • Probably just reduce return to the type ids.
  • (THIS SHOULD BE MOVED TO HAFAH I THINK) But might need additional indexes in HAF itself, so need to figure out how troublesome it is.

/accounts/{account-name}/operations/comments List operations related to account and optionally filtered by permlink, time/blockrange and comment related operations

  • Schema is broken. Probably all schemas need to be checked.
  • Don't really understand this function. Does operation-type only take a subset of all optype ids?
  • ONLY WORKS IF COMMENTSEARCH INDEXES ARE ENABLED. CANT REVIEW FURTHER RIGHT NOW.

/witnesses List all witnesses (both active and standby)

  • change feed_age to last_feed_update

/witnesses/{account-name} Return a single witness given their account name

  • change feed_age to last_feed_update

/witnesses/{account-name}/voters Get information about the voters voting for a given witness

  • For sort order voter, change to "account name of voter"
  • For sort order vests, change to "total voting power = account_vests + proxied_vests of voter"
  • For sort order account_vests, change to "direct vests of voter"
  • For sort order proxied_vests, change to "proxied vests of voter"
  • Replace ??? in sort order: "last time voter voted for the witness"
/witnesses/{account-name}/voters/count Get the number of voters for a witness given their account name

/witnesses/{account-name}/votes/history Get information about each vote cast for this witness

  • For sort order voter, change to "account name of voter"
  • For sort order vests, change to "total voting power = account_vests + proxied_vests of voter"
  • For sort order account_vests, change to "direct vests of voter"
  • For sort order proxied_vests, change to "proxied vests of voter"
  • Eliminate ??? with "time when user performed vote/unvote operation" (note this is different from "voters" method)
/version
/input-type/{input-value} Determines whether the entered value is a block, block hash, transaction hash, or account name
  • ALL APIS: Create tool to auto-generate SWAGGER examples from a specified input.

Miscellaneous notes about hafbe_ui api calls for a "block" page used here just for api analysis (create an issue in hafbe_ui eventually):

  • 2x get_block -> get_block_hafbe_header (2nd call to get head block info) which is /hafbe/blocks/{block-num}/header
  • get_block_raw -> ALMOST DUPS hafah/blocks/{block-num} (block + transactions) which is /hafbe/blocks/{block-num}
  • get_ops_by_block_paging -> /hafbe/blocks/{block-num}/operations (full ops with wild filtering)
  • get_op_count_in_block-> only returns optypeid/count, but this differs from hafbe_endpoints.get_block_op_types(10000) which also has operation_name and is_virtual. Probably hafbe call should match the minimal return of get_op_count_in_block.
  • Probably https://testexplore.openhive.network/block/87586071 makes a call to get_block_raw that it doesn't need unless displaying json view of operations.
Edited by Dan Notestein