Mirroristas/bigchaindb
2
0
Fork 0
mirror of https://github.com/bigchaindb/bigchaindb.git synced 2024-10-13 13:34:05 +00:00
Code Issues Packages Projects Releases Wiki Activity

move blocks and votes to advanced with intro

Browse Source
This commit is contained in:
diminator 2017-01-11 10:48:52 +01:00 committed by tim
parent 4631c93dbf
commit 86be0e5983
2 changed files with 66 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
docs/server/generate_http_server_api_documentation.py
View File

@ -134,7 +134,7 @@ TPLS['get-block-txid-response'] = """\
HTTP/1.1 200 OK
Content-Type: application/json
[%(block)s]
%(block_status)s
"""
@ -194,12 +194,22 @@ def main():
block = Block(transactions=[tx], node_pubkey=node_public, voters=[node_public], signature=signature)
block_json = json.dumps(block.to_dict(), indent=2, sort_keys=True)
block_transfer = Block(transactions=[tx_transfer], node_pubkey=node_public, voters=[node_public], signature=signature)
block_transfer_json = json.dumps(block.to_dict(), indent=2, sort_keys=True)
# vote
DUMMY_SHA3 = '0123456789abcdef' * 4
b = Bigchain(public_key=node_public, private_key=node_private)
vote = b.vote(block.id, DUMMY_SHA3, True)
vote_json = json.dumps(vote, indent=2, sort_keys=True)
# block status
block_status = {
block_transfer.id: 'invalid',
block.id: 'valid'
}
block_status_json = json.dumps(block_status, indent=2, sort_keys=True)
base_path = os.path.join(os.path.dirname(__file__),
'source/drivers-clients/samples')
if not os.path.exists(base_path):
@ -218,6 +228,7 @@ def main():
'public_keys_transfer_last': tx_transfer_last.outputs[0].public_keys[0],
'block': block_json,
'blockid': block.id,
'block_status': block_status_json,
'vote': vote_json}
with open(path, 'w') as handle:
handle.write(code)

95
docs/server/source/drivers-clients/http-client-server-api.rst
View File

@ -298,9 +298,58 @@ Statuses
:statuscode 200: A transaction or block with that ID was found.
:statuscode 404: A transaction or block with that ID was not found.
Blocks
Advanced Usage
--------------------------------
The following endpoints are more advanced and meant for debugging and transparency purposes.
More precisely, the `blocks endpoint <#blocks>`_ allows you to retrieve a block by ``block_id`` as well the list of blocks that
a certain transaction with ``tx_id`` occured in (a transaction can occur in multiple ``invalid`` blocks until it
either gets rejected or validated by the system). This endpoint gives the ability to drill down on the lifecycle of a
transaction
The `votes endpoint <#votes>`_ contains all the voting information for a specific block. So after retrieving the
``block_id`` for a given ``tx_id``, one can now simply inspect the votes that happened at a specific time on that block.
Blocks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. http:get:: /blocks
The unfiltered ``/blocks`` endpoint without any query parameters
returns a list of available block usages and relevant endpoints.
We believe a PUSH rather than a PULL pattern is more appropriate, as the
items returned in the collection would change by the second.
**Example request**:
.. sourcecode:: http
GET /blocks HTTP/1.1
Host: example.com
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
{
"_links": {
"blocks": "https://example.com:9984/api/v1/blocks?tx_id={tx_id}&status={VALID|UNDECIDED|INVALID}",
"docs": "https://docs.bigchaindb.com/projects/server/en/v0.9.0/drivers-clients/http-client-server-api.html",
"item": "https://example.com:9984/api/v1/blocks/{block_id}?status={VALID|UNDECIDED|INVALID}",
"self": "https://example.com:9984/api/v1/blocks"
},
"version" : "0.9.0"
}
:statuscode 200: BigchainDB blocks root endpoint.
.. http:get:: /blocks/{block_id}?status={VALID|UNDECIDED|INVALID}
Get the block with the ID ``block_id``.
@ -336,48 +385,12 @@ Blocks
:statuscode 400: The request wasn't understood by the server, e.g. just requesting ``/blocks`` without the ``block_id``.
:statuscode 404: A block with that ID and a certain ``status`` was not found.
.. http:get:: /blocks
.. http:get:: /blocks?tx_id={tx_id}
The unfiltered ``/blocks`` endpoint without any query parameters
returns a list of available block usages and relevant endpoints.
We believe a PUSH rather than a PULL pattern is more appropriate, as the
items returned in the collection would change by the second.
**Example request**:
.. sourcecode:: http
GET /blocks HTTP/1.1
Host: example.com
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
{
"_links": {
"blocks": "https://example.com:9984/api/v1/blocks?tx_id={tx_id}&status={VALID|UNDECIDED|INVALID}",
"docs": "https://docs.bigchaindb.com/projects/server/en/v0.9.0/drivers-clients/http-client-server-api.html",
"item": "https://example.com:9984/api/v1/blocks/{block_id}?status={VALID|UNDECIDED|INVALID}",
"self": "https://example.com:9984/api/v1/blocks"
},
"version" : "0.9.0"
}
:statuscode 200: BigchainDB blocks root endpoint.
.. http:get:: /blocks?tx_id={tx_id}&status={VALID|UNDECIDED|INVALID}
Retrieve a list of blocks that contain a transaction with the ID ``tx_id``.
Retrieve a list of ``block_id`` with their corresponding status that contain a transaction with the ID ``tx_id``.
Any blocks, be they ``VALID``, ``UNDECIDED`` or ``INVALID`` will be
returned. To filter blocks by their status, use the optional ``status``
querystring.
returned.
.. note::
In case no block was found, an empty list and an HTTP status code
@ -403,7 +416,7 @@ Blocks
Votes
--------------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. http:get:: /votes?block_id={block_id}