bigchaindb / bigchaindb-driver

Official Python driver for BigchainDB
https://www.bigchaindb.com
Apache License 2.0
105 stars 104 forks source link

I find the keyword argument `unspent` in OutputsEndpoint.get ambiguous #275

Closed vrde closed 6 years ago

vrde commented 7 years ago

From the documentation:

unspent (bool) – Whether to get the unconsumed outputs only. Defaults to False, meaning that both consumed, and unconsumed outputs will be returned.

IMO a better keyword is unspent_only. My first interpretation of unspent set to False was: return me everything but unspents.

Another idea (that I think is more explicit) is to add a unspent method to the OutputsEndpoint.

Another thing, transactions has a method called retrieve, while outputs has a method called get, would it make sense in your opinion to unify and use only one term?

sbellem commented 7 years ago

Regarding the ambiguity with respect to how the word "unspent" is used, it would be best to address the issue on the server side, either as a separate issue, or as a comment on the existing issue: https://github.com/bigchaindb/bigchaindb/issues/1214

Up until now, efforts have been made to design the driver without opinions with respect to the HTTP API. This means that the driver reflects how the HTTP API design is. One key reason for this is that people can consult the server-side documentation for the HTTP API and know how to build requests, and what to expect as responses. This could be true for any client in any language as long as the client reflects the server-side HTTP API spec.

sbellem commented 7 years ago

Another thing, transactions has a method called retrieve, while outputs has a method called get, would it make sense in your opinion to unify and use only one term?

The words retrieve and get are used for GET requests such that retrieve is for a GET endpoint that returns one element whereas get is for GET requests that return a list of elements.

Basically, the idea is roughly like so:

HTTP method driver method
GET /tx tx.get()
POST /tx tx.send()
GET /tx/id tx.retrieve(id)
PUT /tx/id tx.update(id)