This is an interface for machines, not humans. This results in a factor
of >2 speedup for large query sets:

Before:

    $ wrk -c1 -d10s -t1 'http://localhost:5000/api/search?limit=1000'
    Running 10s test @ http://localhost:5000/api/search?limit=1000
      1 threads and 1 connections
      Thread Stats   Avg      Stdev     Max   +/- Stdev
        Latency   340.54ms   38.82ms 446.64ms   75.86%
        Req/Sec     2.62      0.49     3.00     62.07%
      29 requests in 10.08s, 88.02MB read
    Requests/sec:      2.88
    Transfer/sec:      8.74MB

After:

    $ wrk -c1 -d10s -t1 'http://localhost:5000/api/search?limit=1000'
    Running 10s test @ http://localhost:5000/api/search?limit=1000
      1 threads and 1 connections
      Thread Stats   Avg      Stdev     Max   +/- Stdev
        Latency   167.97ms   25.03ms 223.00ms   69.49%
        Req/Sec     6.31      2.71    10.00     69.49%
      59 requests in 10.04s, 96.15MB read
    Requests/sec:      5.87
    Transfer/sec:      9.57MB

h/api/search.py

@@ -124,10 +124,13 @@ def search(request_params, user=None):
              request_params.get('uri'))

    query = build_query(request_params)
    results = models.Annotation.search_raw(query, user=user)
    count = models.Annotation.search_raw(query, {'search_type': 'count'},
                                         raw_result=True)
    return {"rows": results, "total": count["hits"]["total"]}
    results = models.Annotation.search_raw(query, user=user, raw_result=True)

    total = results['hits']['total']
    docs = results['hits']['hits']
    rows = [models.Annotation(d['_source'], id=d['_id']) for d in docs]

    return {"rows": rows, "total": total}


def index(user=None):

h/app.py

@@ -97,7 +97,7 @@ def create_api(global_config, **settings):
    config.set_authorization_policy(acl_authz)
    config.set_root_factory('h.api.resources.create_root')

    config.add_renderer('json', JSON(indent=4))
    config.add_renderer('json', JSON())
    config.add_subscriber('h.api.subscribers.set_user_from_oauth',
                          'pyramid.events.ContextFound')
    config.add_tween('h.api.tweens.auth_token')

h/test/views_test.py

@@ -170,16 +170,16 @@ def test_it_adds_a_limit_param_if_none_is_given(self):
        views.stream_atom(request)

        params = request.api_client.get.call_args[1]["params"]
        assert params["limit"] == 1000
        assert "limit" in params

    def test_it_forwards_user_supplied_limits(self):
        """User-supplied ``limit`` params should be forwarded.

        If the user supplies a ``limit`` param < 1000 this should be forwarded
        If the user supplies a ``limit`` param < 500 this should be forwarded
        to the search API.

        """
        for limit in (0, 500, 1000):
        for limit in (0, 250, 500):
            request = mock.MagicMock()
            request.params = {"limit": limit}

@@ -188,40 +188,40 @@ def test_it_forwards_user_supplied_limits(self):
            params = request.api_client.get.call_args[1]["params"]
            assert params["limit"] == limit

    def test_it_ignores_limits_greater_than_1000(self):
        """It doesn't let the user specify a ``limit`` > 1000.
    def test_it_ignores_limits_greater_than_500(self):
        """It doesn't let the user specify a ``limit`` > 500.

        It just reduces the limit to 1000.
        It just reduces the limit to 500.

        """
        request = mock.MagicMock()
        request.params = {"limit": 1001}
        request.params = {"limit": 501}

        views.stream_atom(request)

        params = request.api_client.get.call_args[1]["params"]
        assert params["limit"] == 1000
        assert params["limit"] == 500

    def test_it_falls_back_to_1000_if_limit_is_invalid(self):
        """If the user gives an invalid limit value it falls back to 1000."""
    def test_it_falls_back_to_100_if_limit_is_invalid(self):
        """If the user gives an invalid limit value it falls back to 100."""
        for limit in ("not a valid integer", None, [1, 2, 3]):
            request = mock.MagicMock()
            request.params = {"limit": limit}

            views.stream_atom(request)

            params = request.api_client.get.call_args[1]["params"]
            assert params["limit"] == 1000
            assert params["limit"] == 100

    def test_it_falls_back_to_1000_if_limit_is_negative(self):
        """If given a negative number for limit it falls back to 1000."""
    def test_it_falls_back_to_100_if_limit_is_negative(self):
        """If given a negative number for limit it falls back to 100."""
        request = mock.MagicMock()
        request.params = {"limit": -50}

        views.stream_atom(request)

        params = request.api_client.get.call_args[1]["params"]
        assert params["limit"] == 1000
        assert params["limit"] == 100

    def test_it_forwards_url_params_to_the_api(self):
        """Any URL params are forwarded to the search API."""

h/views.py

@@ -153,14 +153,17 @@ def stream_atom(request):
    params = dict(request.params)

    # The maximum value that this function allows the limit param.
    max_limit = 1000
    default_limit = 100
    max_limit = 500

    try:
        params["limit"] = int(params.get("limit", max_limit))
        params["limit"] = int(params.get("limit", default_limit))
    except (ValueError, TypeError):
        params["limit"] = max_limit
        params["limit"] = default_limit

    if not 0 <= params["limit"] <= max_limit:
    if params["limit"] < 0:
        params["limit"] = default_limit
    if params["limit"] > max_limit:
        params["limit"] = max_limit

    try: