Skip to content

SPS API Plugin

Jump to bottom
Dariusz Kędzierski edited this page Apr 9, 2019 · 37 revisions

SPS API plugin provides RPC api for querying worker proposals in STEEM. It provides following methods:

find_proposals

This method allows to show proposals with given id. This method expects following json structure as parameter:

{
  "id_set" : [list of ids]
}

Result of the call is a vector of structures holding proposal data with given id:

[{
  "id" : proposal id,
  "creator":"blocktrades", 
  "receiver":"treasury", 
  "start_date":"2019-03-01T00:00:00", 
  "end_date":"2019-04-01T00:00:00", 
  "daily_pay":"1500.000 SBD", 
  "subject":"this is subject", 
  "permlink":"mypermalink",
  "total_votes" : number of votes
}]

Curl example: curl --data-binary '{"jsonrpc":"2.0","id":"2","method":"sps_api.find_proposals", "params" : {"id_set" : [1,2,3,4]}}' http://127.0.0.1:8751

list_proposals

This method allows to list all working proposal in the system. This method expects following json structure as parameter:

{
  "start" : starting value for a query,
  "order_by" : results will be sorted by chosen parameter: by_creator, by_start_date, by_end_date, by_total_votes,
  "order_direction" : results can be sorted ascending and descending (direction_ascending, direction_descending),
  "limit" : result count will be limitied to this value,
  "status" : show results only with given status (active, inactive, expired, all, votable),
  "last_id" : optional id of the record to start iteration, useful when record count is greater than limit
}

Note: votable status is a status describing proposal that can be voted so (inactive or active)

Note: please note that start value and parameter chosen in order_by are bound. If you chose by_start_date a start parameter have to be in date format etc.

Result of the call is a vector of structures holding proposal data:

[{
  "id" : proposal id,
  "creator":"blocktrades", 
  "receiver":"treasury", 
  "start_date":"2019-03-01T00:00:00", 
  "end_date":"2019-04-01T00:00:00", 
  "daily_pay":"1500.000 SBD", 
  "subject":"this is subject", 
  "permlink":"mypermalink",
  "total_votes" : number of votes
}]

Curl example: curl --data-binary '{"jsonrpc":"2.0","id":"2","method":"sps_api.list_proposals","params":{"start":"blocktrades", "order_by":"by_creator", "order_direction":"direction_ascending","limit":1,"status":"all"}}' http://127.0.0.1:8751

Or with last_id: curl --data-binary '{"jsonrpc":"2.0","id":"2","method":"sps_api.list_proposals","params":{"start":"blocktrades", "order_by":"by_creator", "order_direction":"direction_ascending","limit":1,"status":"all","last_id":2}}' http://127.0.0.1:8751

list_voter_proposals

This method allows to list all working proposals voted by voters which names begins with string stated in voter field. This method expects following structure as parameter:

{
  "start" : starting value for a query,
  "order_by" : results will be sorted by chosen parameter: by_creator, by_start_date, by_end_date, by_total_votes,
  "order_direction" : results can be sorted ascending and descending (direction_ascending, direction_descending),
  "limit" : result count will be limitied to this value,
  "status" : show results only with given status (active, inactive, expired, all, votable)
  "last_id" : optional id of the record to start iteration, useful when record count is greater than limit
}

**Note**: votable status is a status describing proposal that can be voted so (inactive or active)

Result of the call is a vector of structures holding proposal data:

{
  "blocktrades" : [{
    "id" : proposal id,
    "creator":"blocktrades", 
    "receiver":"treasury", 
    "start_date":"2019-03-01T00:00:00", 
    "end_date":"2019-04-01T00:00:00", 
    "daily_pay":"1500.000 SBD", 
    "subject":"this is subject", 
    "permlink":"mypermalink",
    "total_votes" : number of votes
  }]
}

Curl example: curl --data-binary '{"jsonrpc":"2.0","id":"2","method":"sps_api.list_voter_proposals", "params" : {"start" : "blocktrades","order_by":"by_creator", "order_direction":"direction_ascending","limit":10,"status":"all"}}' http://127.0.0.1:8751

Or with last_id: curl --data-binary '{"jsonrpc":"2.0","id":"2","method":"sps_api.list_voter_proposals", "params" : {"start" : "blocktrades","order_by":"by_creator", "order_direction":"direction_ascending","limit":10,"status":"all","last_id":5}}' http://127.0.0.1:8751

On usage of last_id with list_proposals and list_voter_proposals:

Common user case will be pagination scheme. Lets say that one wants to paginate trough the results with limit 10. In some cases there can be a possibility of obtaining result with the same records with record count greater that limit. In that situation pagination scheme will fail, one will be getting the same results all the time.

To prevent that situation the last_id parameter was introduced, it allows to specify id of the last displayed element. Next query will start from specified id not from the lower/upper bound as usual.

For example, one is using curl call to list voter proposals:

curl --data-binary '{"jsonrpc":"2.0","id":"2","method":"sps_api.list_voter_proposals", "params" : {"start" : "blocktrades","order_by":"by_creator", "order_direction":"direction_ascending","limit":10,"status":"all"}}' http://127.0.0.1:8751

And will get the results:

{
  "blocktrades" : [
     {"id" : 0, "creator":"blocktrades", "receiver":"treasury", "start_date":"2019-03-01T00:00:00",     "end_date":"2019-04-01T00:00:00", "daily_pay":"1500.000 SBD", "subject":"this is subject", "permlink":"mypermalink",    "total_votes" : 0},
     {"id" : 1, "creator":"blocktrades", "receiver":"treasury", "start_date":"2019-03-01T00:00:00",     "end_date":"2019-04-01T00:00:00", "daily_pay":"1500.000 SBD", "subject":"this is subject", "permlink":"mypermalink",    "total_votes" : 0},
     {"id" : 2, "creator":"blocktrades", "receiver":"treasury", "start_date":"2019-03-01T00:00:00",     "end_date":"2019-04-01T00:00:00", "daily_pay":"1500.000 SBD", "subject":"this is subject", "permlink":"mypermalink",    "total_votes" : 0},
     {"id" : 3, "creator":"blocktrades", "receiver":"treasury", "start_date":"2019-03-01T00:00:00",     "end_date":"2019-04-01T00:00:00", "daily_pay":"1500.000 SBD", "subject":"this is subject", "permlink":"mypermalink",    "total_votes" : 0},
     {"id" : 4, "creator":"blocktrades", "receiver":"treasury", "start_date":"2019-03-01T00:00:00",     "end_date":"2019-04-01T00:00:00", "daily_pay":"1500.000 SBD", "subject":"this is subject", "permlink":"mypermalink",    "total_votes" : 0},
     {"id" : 5, "creator":"blocktrades", "receiver":"treasury", "start_date":"2019-03-01T00:00:00",     "end_date":"2019-04-01T00:00:00", "daily_pay":"1500.000 SBD", "subject":"this is subject", "permlink":"mypermalink",    "total_votes" : 0},
     {"id" : 6, "creator":"blocktrades", "receiver":"treasury", "start_date":"2019-03-01T00:00:00",     "end_date":"2019-04-01T00:00:00", "daily_pay":"1500.000 SBD", "subject":"this is subject", "permlink":"mypermalink",    "total_votes" : 0},
     {"id" : 7, "creator":"blocktrades", "receiver":"treasury", "start_date":"2019-03-01T00:00:00",     "end_date":"2019-04-01T00:00:00", "daily_pay":"1500.000 SBD", "subject":"this is subject", "permlink":"mypermalink",    "total_votes" : 0},
     {"id" : 8, "creator":"blocktrades", "receiver":"treasury", "start_date":"2019-03-01T00:00:00",     "end_date":"2019-04-01T00:00:00", "daily_pay":"1500.000 SBD", "subject":"this is subject", "permlink":"mypermalink",    "total_votes" : 0},
     {"id" : 9, "creator":"blocktrades", "receiver":"treasury", "start_date":"2019-03-01T00:00:00",     "end_date":"2019-04-01T00:00:00", "daily_pay":"1500.000 SBD", "subject":"this is subject", "permlink":"mypermalink",    "total_votes" : 0}
   ]
}

As you can see we get 10 records with the same parameters in fields that are sortable (creator, start_date, end_date and total_votes). If there are more that 10 or even 1000 elements of the same type one will never leave first page.

With last_id one can simply make a next call: curl --data-binary '{"jsonrpc":"2.0","id":"2","method":"sps_api.list_voter_proposals", "params" : {"start" : "blocktrades","order_by":"by_creator", "order_direction":"direction_ascending","limit":10,"status":"all","last_id":9}}' http://127.0.0.1:8751

And get next elements:

{
  "blocktrades" : [
     {"id" : 9, "creator":"blocktrades", "receiver":"treasury", "start_date":"2019-03-01T00:00:00",     "end_date":"2019-04-01T00:00:00", "daily_pay":"1500.000 SBD", "subject":"this is subject", "permlink":"mypermalink",    "total_votes" : 0},
     {"id" : 10, "creator":"blocktrades", "receiver":"treasury", "start_date":"2019-03-01T00:00:00",     "end_date":"2019-04-01T00:00:00", "daily_pay":"1500.000 SBD", "subject":"this is subject", "permlink":"mypermalink",    "total_votes" : 0},
     {"id" : 11, "creator":"blocktrades", "receiver":"treasury", "start_date":"2019-03-01T00:00:00",     "end_date":"2019-04-01T00:00:00", "daily_pay":"1500.000 SBD", "subject":"this is subject", "permlink":"mypermalink",    "total_votes" : 0}
  ]
}

Clone this wiki locally