diff --git a/docs/server/generate_http_server_api_documentation.py b/docs/server/generate_http_server_api_documentation.py index d51050d3..6376ae1c 100644 --- a/docs/server/generate_http_server_api_documentation.py +++ b/docs/server/generate_http_server_api_documentation.py @@ -59,6 +59,20 @@ Content-Type: application/json %(tx_transfer_last)s] """ +TPLS['get-assets-request'] = """\ +GET /transactions?operation=CREATE&is_asset=true&public_keys=%(public_keys)s HTTP/1.1 +Host: example.com + +""" + + +TPLS['get-assets-response'] = """\ +HTTP/1.1 200 OK +Content-Type: application/json + +[%(tx)s] +""" + TPLS['post-tx-request'] = """\ POST /transactions/ HTTP/1.1 diff --git a/docs/server/source/drivers-clients/http-client-server-api.rst b/docs/server/source/drivers-clients/http-client-server-api.rst index 90ccc58c..45821afc 100644 --- a/docs/server/source/drivers-clients/http-client-server-api.rst +++ b/docs/server/source/drivers-clients/http-client-server-api.rst @@ -106,7 +106,8 @@ Transactions that include: * `Unfulfilled outputs <#get--transactions?fulfilled=false&public_keys=public_keys>`_ - * `Transactions related to a specific asset <#get--transactions?operation=CREATE|TRANSFER&asset_id=asset_id>`_ + * `Transactions related to a specific asset <#get--transactions?operation=GENESIS|CREATE|TRANSFER&asset_id=asset_id>`_ + * `Listing of assets <#get--transactions?operation=CREATE&is_asset=true&public_keys=public_keys>`_ In this section, we've listed those particular requests, as they will likely to be very handy when implementing your application on top of BigchainDB. @@ -120,12 +121,15 @@ Transactions :query boolean fulfilled: A flag to indicate if transactions with fulfilled conditions should be returned. + :query boolean is_asset: A flag to indicate if the ``asset`` field of the transaction is ``null`` or not. + :query string public_keys: Public key able to validly spend an output of a transaction, assuming the user also has the corresponding private key. :query string operation: One of the three supported operations of a transaction: ``GENESIS``, ``CREATE``, ``TRANSFER``. :query string asset_id: asset ID. + :statuscode 404: BigchainDB does not expose this endpoint. @@ -198,6 +202,37 @@ Transactions :statuscode 200: A list of transactions containing an asset with ID ``asset_id`` was found and returned. :statuscode 400: The request wasn't understood by the server, e.g. the ``asset_id`` querystring was not included in the request. +.. http:get:: /transactions?operation=CREATE&is_asset=true&public_keys={public_keys} + + Get a list of ``CREATE`` transactions that have the asset field defined. + This can serve as a recipe for retrieving your list of assets. + Currently, filtering on specific fields in the ``asset`` or ``metadata`` is assumed to be done clientside. + + This endpoint returns assets only if the transaction they're in are + included in a ``VALID`` or ``UNDECIDED`` block on ``bigchain``. + + :query string operation: One of the three supported operations of a transaction: ``GENESIS``, ``CREATE``, ``TRANSFER``. + + :query boolean is_asset: A flag to indicate if the ``asset`` field of the transaction is ``null`` or not. + + :query string public_keys: Public key able to validly spend an output of a transaction, assuming the user also has the corresponding private key. + + + **Example request**: + + .. literalinclude:: samples/get-assets-request.http + :language: http + + **Example response**: + + .. literalinclude:: samples/get-assets-response.http + :language: http + + + :resheader Content-Type: ``application/json`` + + :statuscode 200: A list of transactions containing an asset and ``public_keys`` found and returned. + :statuscode 400: The request wasn't understood by the server, e.g. the ``is_asset`` querystring was not included in the request. .. http:post:: /transactions