pagination improved

api/helpers.py

@@ -15,3 +15,15 @@ def check_api_key():
             response, 401,
             {'WWW-Authenticate': 'Basic realm="Login Required"'}
         )
+
+
+def pagination_to_dict(pagination):
+    return {
+        'page': pagination.page,
+        'pages': pagination.pages,
+        'next_num': pagination.next_num,
+        'per_page': pagination.per_page,
+        'has_next': pagination.has_next,
+        'has_prev': pagination.has_prev,
+        'total': pagination.total
+    }

api/resources/categories.py

@@ -1,6 +1,7 @@
 from flask import Blueprint, request, jsonify
 from api import db, tasks
 from api.models import Category
+from api.helpers import pagination_to_dict
 
 mod = Blueprint('categories', __name__, url_prefix='/categories')
 
@@ -9,15 +10,13 @@ mod = Blueprint('categories', __name__, url_prefix='/categories')
 def list():
     page = request.args.get('page', 1, type=int)
     per_page = request.args.get('per_page', 10, type=int)
-    categories = Category.query.paginate(page=page, per_page=per_page).items
+    pagination = Category.query.paginate(page=page, per_page=per_page)
     j = {
-        'page': page,
-        'per_page': per_page,
-        'data': [c.to_json() for c in categories]
+        'pagination': pagination_to_dict(pagination),
+        'data': [item.to_json() for item in pagination.items]
     }
     return jsonify(j)
 
-
 @mod.route("/<int:id>", methods=["GET"])
 def show(id):
     category = Category.query.get_or_404(id)

api/resources/designers.py

@@ -2,6 +2,7 @@ from flask import Blueprint, request, jsonify
 from api import db, tasks
 from api.models import Designer
 from api.validators import validate_keys_exists
+from api.helpers import pagination_to_dict
 
 
 mod = Blueprint('designers', __name__, url_prefix='/designers')
@@ -11,11 +12,10 @@ mod = Blueprint('designers', __name__, url_prefix='/designers')
 def list():
     page = request.args.get('page', 1, type=int)
     per_page = request.args.get('per_page', 10, type=int)
-    designers = Designer.query.paginate(page=page, per_page=per_page).items
+    pagination = Designer.query.paginate(page=page, per_page=per_page)
     j = {
-        'page': page,
-        'per_page': per_page,
-        'data': [d.to_json() for d in designers]
+        'pagination': pagination_to_dict(pagination),
+        'data': [item.to_json() for item in pagination.items]
     }
     return jsonify(j)
 

docs/README.md

@@ -16,42 +16,23 @@ API keys should be added to the `API_KEYS` configuration option
 
 ## Pagination
 
-Some resources may contain a large number of objects. Grabbing and handling them all in one request would be extremely inefficient both for the server and the user. Instead a technique known as pagination is used to break up the results into one or more pages of data.
-
-There are two optional query parameters that can be used to control pagination:
+All resources that returns a list of objects has support for pagination. Some examples are search results, product listings and so on. To use the pagination there are two (optional) query parameters that you need to know about:
 
 * `page` The page number starting from 1
-
 * `per_page` The maxium number of items per page (default is 10)
 
-Sample request:
-
-`curl -X GET 'https://api2.photowall.com/designers/page=5&per_page=10'`
-
-The response would look similar to this:
+An example request looks like this:
 
 ```
-{
-    "page": 5,
-    "per_page": 10,
-    "data": [
-        {
-            "commission": 10,
-            "commission_resale": 10,
-            "currency": "SEK",
-            "id": 68,
-            "name": "kooo",
-            "no_follow": 0,
-            "path": "kiia-valikangas",
-            "sort_desc": 0,
-            "territory": "SE",
-            "username": "kooo",
-            "visible_designerpage": 1,
-            "visible_list": 1,
-            "visible_productpage": 1,
-            "visible_search": 1
-        },
-        // results has been truncated for readability
-    ]
-}
+$ curl -X GET https://api2.photowall.com/designers/page=5&per_page=10 -u mykey
 ```
+
+The response will contain a pagination object with the following attributes:
+
+* `page` The current page number
+* `pages` The total number of pages
+* `next_num` Number of the next page
+* `per_page` The number of items to be displayed on a page
+* `has_next` True if a next page exists
+* `has_prev` True if a previous page exists
+* `total` The total number of items