Merge pull request #35 from strongloop/api-explorer

Add section for api explorer to docs

docs.json

@@ -6,8 +6,8 @@
     "docs/gettingstarted.md",
     "docs/resources.md",
     "docs/concepts.md",
-    "docs/apiexplorer.md",
     "docs/cli.md",
+    "docs/apiexplorer.md",
     "docs/api.md",
     "docs/ios.md",
     "docs/js.md",

docs/apiexplorer.md

@@ -1,5 +1,159 @@
 ## API Explorer
 
-***Raymond-- Please insert here***
+LoopBack helps you build APIs for mobile applications. As you follow the steps
+to create a project and add models using the `slc lb` command line tool, REST
+APIs are automatically added to your application.
 
----
+Now we have a handful of REST APIs. It would be nice to see the list of APIs and
+try them out without writing code. We can do that! LoopBack provides a Web based
+API explorer out of the box to document and explore REST APIs for the models.
+
+Let's give a try first.
+
+### API Explorer UI
+
+Step 1: Run the sample application
+
+    $ cd sls-sample-app
+    $ slc run app
+
+
+Step 2: Open your browser and point to http://localhost:3000/explorer. You'll
+see a list of REST API endpoints as illustrated below.
+
+![Resource Listing](assets/explorer-listing.png)
+
+The endpoints are grouped by the model names. Each endpoint consists of a list
+of operations for the model.
+
+Step 3: Click on one of the endpoint paths (such as /locations) to see available
+operations for a given model.
+
+![API Endpoint](assets/explorer-endpoint.png)
+
+Great, now you see the CRUD operations mapped to HTTP verbs and paths.
+
+Step 4: Click on a given operation to see the signature
+
+![API Spec](assets/explorer-api.png)
+
+Please note each operation has the HTTP verb, path, description, response model,
+and a list of request parameters.
+
+Step 5: Try to invoke an operation
+
+Fill in the parameters, and then click on `Try it out!` button.
+
+Here we go:
+
+![Request/Response](assets/explorer-req-res.png)
+
+Cool, we can invoke the REST APIs without writing code!
+
+You might be curious about the magic behind it all. Let's reveal a bit to you.
+
+### REST API specs
+
+LoopBack API Explorer is built on top of the popular
+[Swagger Framework](https://github.com/wordnik/swagger-core/wiki). There are two
+components involved.
+
+1. LoopBack builds up formal specifications of the REST APIs using the knowledge of
+model definitions, JavaScript method declarations, and remote mappings. The
+specifications are served over the following endpoints.
+
+2. The wonderful Web UI is brought you by [Swagger UI](https://github.com/strongloop/swagger-ui).
+Swagger UI is a collection of HTML, Javascript, and CSS assets that dynamically
+generate beautiful documentation and sandbox from the REST API specifications.
+
+#### Resource Listing
+The first part is a listing of the REST APIs.
+
+- http://localhost:3000/swagger/resources
+
+
+    {
+      "swaggerVersion": "1.1",
+      "basePath": "http://localhost:3000",
+      "apis": [
+        {
+          "path": "/swagger/ammo"
+        },
+        {
+          "path": "/swagger/customers"
+        },
+        {
+          "path": "/swagger/inventory"
+        },
+        {
+          "path": "/swagger/locations"
+        },
+        {
+          "path": "/swagger/weapons"
+        }
+      ]
+    }
+
+#### Resource Operations
+The second part describes all operations of a given model.
+
+- http://localhost:3000/swagger/locations
+
+
+    {
+      "swaggerVersion": "1.1",
+      "basePath": "http://localhost:3000",
+      "apis": [
+        {
+          "path": "/locations",
+          "operations": [
+            {
+              "httpMethod": "POST",
+              "nickname": "locations_create",
+              "responseClass": "object",
+              "parameters": [
+                {
+                  "paramType": "body",
+                  "name": "data",
+                  "description": "Model instance data",
+                  "dataType": "object",
+                  "required": false,
+                  "allowMultiple": false
+                }
+              ],
+              "errorResponses": [],
+              "summary": "Create a new instance of the model and persist it into the data source",
+              "notes": ""
+            }
+          ]
+        },
+        ...
+        {
+          "path": "/locations/{id}",
+          "operations": [
+            {
+              "httpMethod": "GET",
+              "nickname": "locations_findById",
+              "responseClass": "any",
+              "parameters": [
+                {
+                  "paramType": "path",
+                  "name": "id",
+                  "description": "Model id",
+                  "dataType": "any",
+                  "required": true,
+                  "allowMultiple": false
+                }
+              ],
+              "errorResponses": [],
+              "summary": "Find a model instance by id from the data source",
+              "notes": ""
+            }
+          ]
+        },
+        ...
+      ]
+    }
+
+**Note: The API specifications will be enhanced in future releases to include
+the model definitions.**