diff --git a/bigchaindb/backend/query.py b/bigchaindb/backend/query.py index f989c8b1..8cc5d2c8 100644 --- a/bigchaindb/backend/query.py +++ b/bigchaindb/backend/query.py @@ -381,6 +381,9 @@ def text_search(conn, search, *, language='english', case_sensitive=False, Returns: :obj:`list` of :obj:`dict`: a list of assets + + Raises: + OperationError: If the backend does not support text search """ raise OperationError('This query is only supported when running ' diff --git a/bigchaindb/core.py b/bigchaindb/core.py index 923cb8a8..f6611e7d 100644 --- a/bigchaindb/core.py +++ b/bigchaindb/core.py @@ -621,6 +621,16 @@ class Bigchain(object): return backend.query.write_assets(self.connection, assets) def text_search(self, search, *, limit=0): + """ + Return an iterator of assets that match the text search + + Args: + search (str): Text search string to query the text index + limit (int, optional): Limit the number of returned documents. + + Returns: + iter: An iterator of assets that match the text search. + """ assets = backend.query.text_search(self.connection, search, limit=limit) # TODO: This is not efficient. There may be a more efficient way to diff --git a/bigchaindb/web/routes.py b/bigchaindb/web/routes.py index b20f8d40..d1fa6d26 100644 --- a/bigchaindb/web/routes.py +++ b/bigchaindb/web/routes.py @@ -1,6 +1,7 @@ """ API routes definition """ from flask_restful import Api from bigchaindb.web.views import ( + assets, blocks, info, statuses, @@ -25,6 +26,7 @@ def r(*args, **kwargs): ROUTES_API_V1 = [ r('/', info.ApiV1Index), + r('assets/', assets.AssetListApi), r('blocks/', blocks.BlockApi), r('blocks/', blocks.BlockListApi), r('statuses/', statuses.StatusApi), diff --git a/bigchaindb/web/views/assets.py b/bigchaindb/web/views/assets.py new file mode 100644 index 00000000..7639b78f --- /dev/null +++ b/bigchaindb/web/views/assets.py @@ -0,0 +1,50 @@ +"""This module provides the blueprint for some basic API endpoints. + +For more information please refer to the documentation: http://bigchaindb.com/http-api +""" +import logging + +from flask_restful import reqparse, Resource +from flask import current_app + +from bigchaindb.backend.exceptions import OperationError +from bigchaindb.web.views.base import make_error + +logger = logging.getLogger(__name__) + + +class AssetListApi(Resource): + def get(self): + """API endpoint to perform a text search on the assets. + + Args: + search (str): Text search string to query the text index + limit (int, optional): Limit the number of returned documents. + + Return: + A list of assets that match the query. + """ + parser = reqparse.RequestParser() + parser.add_argument('search', type=str, required=True) + parser.add_argument('limit', type=int) + args = parser.parse_args() + + if not args['search']: + return make_error(400, 'text_search cannot be empty') + if not args['limit']: + # if the limit is not specified do not pass None to `text_search` + del args['limit'] + + pool = current_app.config['bigchain_pool'] + + with pool() as bigchain: + assets = bigchain.text_search(**args) + + try: + # This only works with MongoDB as the backend + return list(assets) + except OperationError as e: + return make_error( + 400, + '({}): {}'.format(type(e).__name__, e) + ) diff --git a/docs/server/source/http-client-server-api.rst b/docs/server/source/http-client-server-api.rst index eb462d25..9fd7aee5 100644 --- a/docs/server/source/http-client-server-api.rst +++ b/docs/server/source/http-client-server-api.rst @@ -270,6 +270,118 @@ Statuses :statuscode 404: A block with that ID was not found. +Assets +-------------------------------- + +.. http:get:: /api/v1/assets + + Return all the assets that match a given text search. + + :query string text search: Text search string to query. + :query int limit: (Optional) Limit the number of returned assets. Defaults + to ``0`` meaning return all matching assets. + + .. note:: + + Currently this enpoint is only supported if the server is running + MongoDB as the backend. + +.. http:get:: /api/v1/assets?search={text_search} + + Return all assets that match a given text search. The asset is returned + with the ``id`` of the transaction that created the asset. + + If no assets match the text search it returns an empty list. + + If the text string is empty or the server does not support text search, + a ``400`` is returned. + + The results are sorted by text score. + For more information about the behavior of text search see `MongoDB text + search behavior `_ + + **Example request**: + + .. sourcecode:: http + + GET /api/v1/assets/?search=bigchaindb HTTP/1.1 + Host: example.com + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-type: application/json + + [ + { + "data": {"msg": "Hello BigchainDB 1!"}, + "id": "51ce82a14ca274d43e4992bbce41f6fdeb755f846e48e710a3bbb3b0cf8e4204" + }, + { + "data": {"msg": "Hello BigchainDB 2!"}, + "id": "b4e9005fa494d20e503d916fa87b74fe61c079afccd6e084260674159795ee31" + }, + { + "data": {"msg": "Hello BigchainDB 3!"}, + "id": "fa6bcb6a8fdea3dc2a860fcdc0e0c63c9cf5b25da8b02a4db4fb6a2d36d27791" + } + ] + + :resheader Content-Type: ``application/json`` + + :statuscode 200: The query was executed successfully. + :statuscode 400: The query was not executed successfully. Returned if the + text string is empty or the server does not support + text search. + +.. http:get:: /api/v1/assets?search={text_search}&limit={n_documents} + + Return at most ``n`` assets that match a given text search. + + If no assets match the text search it returns an empty list. + + If the text string is empty or the server does not support text search, + a ``400`` is returned. + + The results are sorted by text score. + For more information about the behavior of text search see `MongoDB text + search behavior `_ + + **Example request**: + + .. sourcecode:: http + + GET /api/v1/assets/?search=bigchaindb&limit=2 HTTP/1.1 + Host: example.com + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-type: application/json + + [ + { + "data": {"msg": "Hello BigchainDB 1!"}, + "id": "51ce82a14ca274d43e4992bbce41f6fdeb755f846e48e710a3bbb3b0cf8e4204" + }, + { + "data": {"msg": "Hello BigchainDB 2!"}, + "id": "b4e9005fa494d20e503d916fa87b74fe61c079afccd6e084260674159795ee31" + }, + ] + + :resheader Content-Type: ``application/json`` + + :statuscode 200: The query was executed successfully. + :statuscode 400: The query was not executed successfully. Returned if the + text string is empty or the server does not support + text search. + + Advanced Usage -------------------------------- diff --git a/tests/web/test_assets.py b/tests/web/test_assets.py new file mode 100644 index 00000000..0f335ef2 --- /dev/null +++ b/tests/web/test_assets.py @@ -0,0 +1,83 @@ +import pytest + +ASSETS_ENDPOINT = '/api/v1/assets/' + + +def test_get_assets_with_empty_text_search(client): + res = client.get(ASSETS_ENDPOINT + '?search=') + assert res.json == {'status': 400, + 'message': 'text_search cannot be empty'} + assert res.status_code == 400 + + +def test_get_assets_with_missing_text_search(client): + res = client.get(ASSETS_ENDPOINT) + assert res.status_code == 400 + + +@pytest.mark.genesis +def test_get_assets(client, b): + from bigchaindb.models import Transaction + from bigchaindb.backend.mongodb.connection import MongoDBConnection + + if isinstance(b.connection, MongoDBConnection): + # test returns empty list when no assets are found + res = client.get(ASSETS_ENDPOINT + '?search=abc') + assert res.json == [] + assert res.status_code == 200 + + # create asset + asset = {'msg': 'abc'} + tx = Transaction.create([b.me], [([b.me], 1)], + asset=asset).sign([b.me_private]) + # create block + block = b.create_block([tx]) + b.write_block(block) + # vote valid + vote = b.vote(block.id, b.get_last_voted_block().id, True) + b.write_vote(vote) + + # test that asset is returned + res = client.get(ASSETS_ENDPOINT + '?search=abc') + assert res.status_code == 200 + assert len(res.json) == 1 + assert res.json[0] == { + 'data': {'msg': 'abc'}, + 'id': tx.id + } + else: + # test that the correct error is returned if not running MongoDB + res = client.get(ASSETS_ENDPOINT + '?search=abc') + assert res.status_code == 400 + assert res.json['message'].startswith('(OperationError)') + + +@pytest.mark.genesis +def test_get_assets_limit(client, b): + from bigchaindb.models import Transaction + from bigchaindb.backend.mongodb.connection import MongoDBConnection + + if isinstance(b.connection, MongoDBConnection): + # create two assets + asset1 = {'msg': 'abc 1'} + asset2 = {'msg': 'abc 2'} + tx1 = Transaction.create([b.me], [([b.me], 1)], + asset=asset1).sign([b.me_private]) + tx2 = Transaction.create([b.me], [([b.me], 1)], + asset=asset2).sign([b.me_private]) + # create block + block = b.create_block([tx1, tx2]) + b.write_block(block) + # vote valid + vote = b.vote(block.id, b.get_last_voted_block().id, True) + b.write_vote(vote) + + # test that both assets are returned without limit + res = client.get(ASSETS_ENDPOINT + '?search=abc') + assert res.status_code == 200 + assert len(res.json) == 2 + + # test that only one asset is returned when using limit=1 + res = client.get(ASSETS_ENDPOINT + '?search=abc&limit=1') + assert res.status_code == 200 + assert len(res.json) == 1