P5-802 add pagination

api/models/category.py

@@ -23,15 +23,12 @@ class Category(db.Model):
         path = slugify(path)
         return path
 
-    def to_json(self, nested=False):
-        j = {
+    def to_json(self):
+        return {
             'id': self.id,
-            'name': self.name
+            'name': self.name,
+            'texts': [t.to_json() for t in self.texts]
         }
-        if nested:
-            j['texts'] = [t.to_json() for t in self.texts]
-
-        return j
 
 
 class CategoryTexts(db.Model):

api/resources/categories.py

@@ -7,14 +7,21 @@ mod = Blueprint('categories', __name__, url_prefix='/categories')
 
 @mod.route("/", methods=["GET"])
 def list():
-    categories = Category.query.all()
-    return jsonify(data=[c.to_json() for c in categories])
+    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
+    j = {
+        'page': page,
+        'per_page': per_page,
+        'data': [c.to_json() for c in categories]
+    }
+    return jsonify(j)
 
 
 @mod.route("/<int:id>", methods=["GET"])
 def show(id):
     category = Category.query.get_or_404(id)
-    return jsonify(category.to_json(nested=True))
+    return jsonify(category.to_json())
 
 
 @mod.route("/<id>", methods=["PUT"])

api/resources/designers.py

@@ -9,8 +9,15 @@ mod = Blueprint('designers', __name__, url_prefix='/designers')
 
 @mod.route("/", methods=["GET"])
 def list():
-    designers = Designer.query.all()
-    return jsonify(data=[d.to_json() for d in designers])
+    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
+    j = {
+        'page': page,
+        'per_page': per_page,
+        'data': [d.to_json() for d in designers]
+    }
+    return jsonify(j)
 
 
 @mod.route("/", methods=["POST"])

docs/README.md

@@ -12,4 +12,46 @@ Authentication to the API is performed via HTTP Basic Auth. The user should prov
 ```
 $ curl http://localhost:5000/designers/ -u mykey:
 ```
-API keys should be added to the `API_KEYS` configuration option
+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:
+
+* `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:
+
+```
+{
+    "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
+    ]
+}
+```