From 9c00e4b256a0ab7f208efa6730c953a9b6df944a Mon Sep 17 00:00:00 2001
From: Raymond Feng <raymond@strongloop.com>
Date: Thu, 29 Aug 2013 13:52:00 -0700
Subject: [PATCH] Update REST doc based on the PR feedback

---
 docs/rest.md | 88 +++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 73 insertions(+), 15 deletions(-)

diff --git a/docs/rest.md b/docs/rest.md
index 867998d4..2a6c5dfb 100644
--- a/docs/rest.md
+++ b/docs/rest.md
@@ -35,7 +35,7 @@ To expose a JavaScript method as REST API, we can simply describe the method as
 follows:
 
     loopback.remoteMethod(
-      RentalLocation.nearby,
+      Location.nearby,
       {
         description: 'Find nearby locations around the geo point',
         accepts: [
@@ -61,6 +61,25 @@ optional description
 For POST and PUT requests, the request body must be JSON, with the Content-Type
 header set to application/json.
 
+#### Encode the JSON object as query string
+
+LoopBack uses the syntax from [node-querystring](https://github.com/visionmedia/node-querystring)
+to encode JSON objects or arrays as query string. For example,
+
+    user[name][first]=John&user[email]=callback@strongloop.com
+    ==>
+    { user: { name: { first: 'John' }, email: 'callback@strongloop.com' } }
+
+    user[names][]=John&user[names][]=Mary&user[email]=callback@strongloop.com
+    ==>
+    { user: { names: ['John', 'Mary'], email: 'callback@strongloop.com' }}
+
+    items=a&items=b
+    ==> { items: ['a', 'b'] }
+
+For more examples, please check out [node-querystring](https://github.com/visionmedia/node-querystring/blob/master/test/parse.js)
+
+
 ### Response Format
 
 The response format for all requests is a JSON object or array if present. Some
@@ -74,9 +93,10 @@ The response for an error is in the following format:
 
     {
     "error": {
-    "message": "could not find a model with id 1",
-    "stack": "Error: could not find a model with id 1\n ...",
-    "statusCode": 404
+        "message": "could not find a model with id 1",
+        "stack": "Error: could not find a model with id 1\n ...",
+        "statusCode": 404
+        }
     }
 
 ###Generated APIs
@@ -207,18 +227,56 @@ Find all instances of the model matched by filter from the data source
 ####Arguments
 * **filter** The filter that defines where, order, fields, skip, and limit
 
-Properties for the filter object:
+ - **where** `Object` { key: val, key2: {gt: 'val2'}} The search criteria
+   - Format: {key: val} or {key: {op: val}}
+   - Operations:
+     - gt: >
+     - gte: >=
+     - lt: <
+     - lte: <=
+     - between
+     - inq: IN
+     - nin: NOT IN
+     - neq: !=
+     - like: LIKE
+     - nlike: NOT LIKE
 
-    where - Object { key: val, key2: {gt: 'val2'}}
-    include - String, Object or Array.
-    order - String "key1 ASC, key2 DESC"
-    limit - Number The max number of items
-    skip - Number The number of items to be skipped
-    fields - Object|Array|String A list of properties to be included or excluded
-        ['foo'] or 'foo' - include only the foo property
-        ['foo', 'bar'] - include the foo and bar properties
-        {foo: true} - include only foo
-        {bat: false} - include all properties, exclude bat
+ - **include** `String`, `Object` or `Array` Allows you to load relations of several objects and optimize numbers of requests.
+    - Format:
+      - 'posts': Load posts
+      - ['posts', 'passports']: Load posts and passports
+      - {'owner': 'posts'}: Load owner and owner's posts
+      - {'owner': ['posts', 'passports']}: Load owner, owner's posts, and owner's passports
+      - {'owner': [{posts: 'images'}, 'passports']}: Load owner, owner's posts, owner's posts' images, and owner's passports
+
+ - **order** `String` The sorting order
+   - Format: 'key1 ASC, key2 DESC'
+
+ - **limit** `Number` The maximum number of instances to be returned
+ - **skip** `Number` Skip the number of instances
+ - **offset** `Number` Alias for skip
+
+ - **fields** `Object|Array|String` The included/excluded fields
+  - `['foo']` or `'foo'` - include only the foo property
+  - `['foo', 'bar']` - include the foo and bar properties
+  - `{foo: true}` - include only foo
+  - `{bat: false}` - include all properties, exclude bat
+
+For example,
+
+ - '/weapons': Weapons
+ - '/weapons/2': A weapon by id
+ - '/weapons?filter[limit]=2&filter[offset]=5': Paginated Weapons
+ - '/weapons?filter[where][name]=M1911': Weapons with name M1911
+ - '/weapons?filter[where][audibleRange][lt]=10': Weapons with audioRange < 10
+ - '/weapons?filter[fields][name]=1&filter[fields][effectiveRange]=1': Only name and effective ranges
+ - '/weapons?filter[where][effectiveRange][gt]=900&filter[limit]=3': The top 3 weapons with a range over 900 meters
+ - '/weapons?filter[order]=audibleRange%20DESC&filter[limit]=3': The loudest 3 weapons
+
+ - '/locations': Locations
+ - '/locations/nearby?here[lat]=37.587409&here[lng]=-122.338225': Locations nearby
+ - '/locations?filter[where][geo][near]=153.536,-28.1&filter[limit]=3': The 3 closest locations to a given geo point
+ - '/locations/87/inventory': The inventory for store 87
 
 ####Example Request
     curl http://localhost:3000/locations