Update readme to fix some details and be more explicit about return t…

…ypes

README.md

@@ -24,37 +24,47 @@ Authorization: Token bkayZOMvuy8aZOhIgxq94K9Oe7Y70Hw55
 There are currently three endpoints for the Luath API.
 
 ### Lists
-The lists endpoint can be accessed on `/lists`. This endpoint will return an array of the lists that are currently monitored by Luath with the details about each list.
+The lists endpoint can be accessed on `/lists`. This endpoint will return an object containing an array of the lists that are currently monitored by Luath with the details about each list.
 
 ```
-[
-  {
-    "id": 1,
-    "name": "swift-corelibs-dev",
-    "email": "[email protected]",
-    "description": "Discussion of the implementation of the Swift core libraries."
-  }
+{
+  "count": 5,
+  "next": null,
+  "previous": null,
+  "results": [
+    {
+      "id": 1,
+      "name": "swift-corelibs-dev",
+      "email": "[email protected]",
+      "description": "Discussion of the implementation of the Swift core libraries."
+    }
   ...
-]
+  ]
+}
 ```
 
 ### Messages
-You can get the messages in a list by querying the `messages` resource. Messages in a list are available under `/lists/{list-id}/messages`. This returns a list of messages and their associated data. You must pass in a limit and an offset for this endpoint as query strings.
+You can get the messages in a list by querying the `messages` resource. Messages in a list are available under `/lists/{list-id}/messages`. This returns a list of messages and their associated data.
 
 ```
-[
-  {
-    "id": "[email protected]",
-    "from": "[email protected]",
-    "from_name": "James Lee",
-    "in_reply_to": null,
-    "date": "2015-12-08T12:23:19.000Z",
-    "datestring": "Tue, 8 Dec 2015 12:23:19 +0000",
-    "subject": "[swift-corelibs-dev] NSAttributedString attributesAtIndex return an\n\toptional.",
-    "content": "Hi all,\n\nBeen playing around with NSAttributedString ...",
-    "listId": 1
-  }
-]
+{
+  "count": 918,
+  "next": "http://www.luath.org/api/v1/lists/1/messages?limit=100&offset=100",
+  "previous": null,
+  "results": [
+    {
+      "id": "[email protected]",
+      "from": "[email protected]",
+      "from_name": "James Lee",
+      "in_reply_to": null,
+      "date": "2015-12-08T12:23:19.000Z",
+      "datestring": "Tue, 8 Dec 2015 12:23:19 +0000",
+      "subject": "[swift-corelibs-dev] NSAttributedString attributesAtIndex return an\n\toptional.",
+      "content": "Hi all,\n\nBeen playing around with NSAttributedString ...",
+      "listId": 1
+    }
+  ]
+}
 ...
 ```
 
@@ -75,8 +85,11 @@ You can get the messages in a list by querying the `messages` resource. Message
 }
 ```
 
+### Pagination
+The `messages` endpoint is paginated, and you can read different pages by providing an `offset` query parameter. You can also provide a `limit` parameter, but it is optional and the default limit is 100 messages. If you don't provide or provide an invalid `offset` the API will return the first page (offset 0, limit 100).
+
 ### Response Codes
-You can expect all successful response codes to be `200`. If there is an error, you will receive a `500` with a message detailing the error, if there are any details. If there is an error in the input you provided, you will receive a `403` status code with a message detailing what the expected inputs are.
+You can expect all successful response codes to be `200`. If there is an error, you will receive a `500` with a message detailing the error, if there are any details. If you don't provide an authorization token, or the token is not valid, you will receive a `401` response.
 
 # Contributing
 Thanks for thinking about contributing to Luath. If you'd like to help out, open an issue so we can talk about what you're wanting to do, and when we've fleshed out the details, I'll be happy to look at a pull request.