P5-802 add pagination

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
+    ]
+}
+```