From 92d3732a09e486a8a122c2628770dd6ae668ed87 Mon Sep 17 00:00:00 2001
From: Martin <me.carlsson@gmail.com>
Date: Thu, 18 Aug 2016 17:39:24 +0200
Subject: [PATCH] P5-802 add pagination

---
 api/models/category.py      | 11 ++++------
 api/resources/categories.py | 13 ++++++++---
 api/resources/designers.py  | 11 ++++++++--
 docs/README.md              | 44 ++++++++++++++++++++++++++++++++++++-
 4 files changed, 66 insertions(+), 13 deletions(-)

diff --git a/api/models/category.py b/api/models/category.py
index b2ceab7..e668f9e 100644
--- a/api/models/category.py
+++ b/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):
diff --git a/api/resources/categories.py b/api/resources/categories.py
index 9c22002..f1fe0f5 100644
--- a/api/resources/categories.py
+++ b/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"])
diff --git a/api/resources/designers.py b/api/resources/designers.py
index 81f76bb..bb3079a 100644
--- a/api/resources/designers.py
+++ b/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"])
diff --git a/docs/README.md b/docs/README.md
index af03112..f0d545b 100644
--- a/docs/README.md
+++ b/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
\ No newline at end of file
+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
+    ]
+}
+```