Add documentation for pagination.

docs/pagination.md

@@ -0,0 +1,71 @@
+# Pagination
+
+Pagination is supported using the metadata support that is built into Ember Data. The
+metadata from Django REST Framework paginated list views is updated on every request
+to sever.
+
+
+## Retrieving the Metadata
+
+To get a page of records simply run a find request with the `page` query param:
+
+```js
+var result = this.store.find("post", {
+  page: 1
+});
+```
+
+It's possible to override the server-side page size by also including the `page_size`
+query param:
+
+```js
+var result = this.store.find("post", {
+  page: 1,
+  page_size: 10
+});
+```
+
+After the request returns, you can access the metadata either with `store.metadataFor`:
+
+```js
+var meta = this.store.metadataFor("post");
+```
+
+Or you can access the metadata just for this query:
+
+```js
+var meta = result.get("content.meta");
+```
+
+NB If you run a find request against a paginated list view without query params, only
+`store.metadataFor` will have metadata set. This is how metadata works in Ember Data.
+
+
+## Metadata Properties
+
+The metadata consists of three properties which gives applications enough information
+to paginate through a Django REST Framework paginated list view.
+
+* `count` - The total number of records available. This can be used along with the page
+            size to calculate the total number of pages.
+* `next` - The next page number or `null` when there is no next page.
+* `previous` -The previous page number or `null` when there is no previous page.
+
+The `next` and `previous` page number can be used directly as the value to the `page`
+query param on subsequent find requests. Of course `null` is not a valid value for the
+`page` query param so applications need to check this condition before using it.
+
+```js
+if (meta.next) {
+  store.find('post', {page: meta.next}
+}
+```
+
+## Integration with 3rd Party Libraries
+
+* Ember CLI Pagination
+
+https://github.com/mharris717/ember-cli-pagination
+
+It's should be possible to use the pagination metadata with Ember CLI Pagination. If you
+get this working, please consider submitting a pull request documenting the configuration.

tests/integration/pagination-test.js

@@ -121,7 +121,6 @@ test('Retrieve list of paginated records', function() {
     store.find('post').then(function(response) {
       ok(response);
 
-
       equal(response.get('length'), 4);
 
       // Test the camelCase and non-camelCase fields of a paginated result.