Add docs for mapping between UI actions and API calls

API.md

@@ -0,0 +1,185 @@
+## Temporary API endpoints docs (initial coverage)
+
+
+### UI and API relationships
+============================
+
+Description of what API calls are made when user performs UI actions.
+
+
+
+#### New box (press "New box" button)
+
+```
+  POST /contexts
+    request:
+      name: uuid()
+      owner:
+        github: user_github_id
+    response:
+      new context object
+
+  POST /contexts/:new_context_id/versions
+    request: empty
+    response:
+      new context version object
+
+  POST /builds
+    request:
+      contextVersions: [:new_context_version_id]
+      owner:
+        github: user_github_id
+    response:
+      new build object
+```
+
+#### Add repo to the box (press "Add repository to the box" area)
+
+```
+  POST /contexts/:new_context_id/versions/:new_context_version_id/appCodeversions
+    request:
+      branch: branch name
+      commit: commit
+      repo: full repo name (owner/name)
+    response:
+      new app version code
+```
+
+
+### Select Docker template (click on template)
+
+```
+  PUT /contexts/:new_context_id/versions/:new_context_version_id/infraCodeVersion/actions/copy?sourceInfraCodeVersion=5452c94e72fd5a2400e72430
+  GET /contexts/:new_context_id/versions/:new_context_version_id/files
+  GET /contexts/:new_context_id/versions/:new_context_version_id/files/Dockerfile
+```
+
+### Enter new Dockerfile content
+
+```
+  PATCH /contexts/:new_context_id/versions/:new_context_version_id/files/Dockerfile
+```
+
+### Enter box name and press "Create box"
+
+```
+  POST /builds/:new_build_id/actions/build
+    request:
+      message: 'Initial Build'
+    response:
+      updated build object
+
+  POST /instances
+    request:
+      build: 'Initial Build'
+      name: instance name
+      owner:
+        github: user_github_id
+    response:
+      new instance object
+```
+
+
+### Rename box
+
+```
+  PATCH /instances/:id
+    request:
+      name: new name
+    response:
+      update instance object
+```
+
+
+### Edit box
+
+```
+  POST /builds/:build_id/actions/copy?deep=true
+    request: empty
+    response:
+      new build object
+
+  // change docker file
+  PATCH /contexts/:context_id/versions/:context_version_id/files/Dockerfile
+    request:
+      body: docker file content
+    response:
+      file object
+  // build a build
+  POST /builds/:new_build_id/actions/build
+    request:
+      message: "Manual build"
+    response:
+      build object
+  // poll container until found. Containers will always have one container!
+  GET /instances/:instance_id/containers
+    response: [new container object]
+  // patch instance with a new build
+  PATCH /instances/:instance_id/
+    request:
+      build: build_id
+    response:
+      instance object
+```
+
+
+### Stop box
+
+```
+  PUT /instances/:instance_id/actions/stop
+```
+
+### Stop box
+
+```
+  PUT /instances/:instance_id/actions/stop
+```
+
+### Fork box
+
+```
+  POST /instances/:instance_id/actions/copy
+    request:
+      name: forked box name
+    response:
+      instance object
+```
+
+
+### Update box to commit version
+
+```
+  // create new context verison
+  POST /contexts/:context_id/versions
+    request:
+      infraCodeVersion: id of existing infracode version
+    response:
+      new contex version withou appCode
+  // create new app code version
+  POST /contexts/:context_id/versions/:created_context_version_id/appCodeVersions/
+    request:
+      branch:
+      commit:
+      repo:
+    response:
+      new app code version
+  // create new build
+  POST /builds
+    request: 
+      owner: github owner data
+      contextVersions: [context version id]
+    response:
+      new build object
+  // build a build
+  POST /builds/:new_build_id/actions/build
+    request:
+      message: "Update application code version(s)"
+    response:
+      build object
+  // patch instance with a new build
+  PATCH /instances/:instance_id/
+    request:
+      build: build_id
+    response:
+      instance object
+```

README.md

@@ -3,10 +3,10 @@
 Application Components
 ==========
 #### Express
-/lib/app.js
+/lib/express-app.js
 
 #### Routes
-/lib/routes.js
+/lib/routes/**/*.js
 
 #### Mongo
 Models  - /lib/models/mongo/*.js
@@ -15,7 +15,7 @@ Schemas - /lib/models/mongo/schemas/*.js
 #### Tests
 Behavioral tests (BDD) - /test
 Unit Tests - /unit
-Lab - Testing Framework - [spumko/lab](https://github.com/spumko/lab)
+Lab - Testing Framework - [hapijs/lab](https://github.com/hapijs/lab)
 
 Running Tests
 =============
@@ -27,47 +27,43 @@ npm test
 
 Granular:
 
-Lint: `npm run lint`  
-All BDD: `npm run bdd`  
-Pass additional arguments to BDD: `npm run bdd -- -d`  
-BDD one file: `npm run bdd -- test/path/to/file.js`  
-BDD Watch: `npm run bdd-watch`  
-BDD Watch w/ one test file: `npm run bdd-watch -- test/path/to/file.js`  
-All Unit: `npm run unit`  
+Lint: `npm run lint`
+All BDD: `npm run bdd`
+Pass additional arguments to BDD: `npm run bdd -- -d`
+BDD one file: `npm run bdd -- test/path/to/file.js`
+BDD Watch: `npm run bdd-watch`
+BDD Watch w/ one test file: `npm run bdd-watch -- test/path/to/file.js`
+All Unit: `npm run unit`
 
 Opinions
 ========
 #### Restful resource urls
-Create - POST   - /resources  
-Read   - GET    - /resources/:id  
-Update - PATCH  - /resources/:id  *PATCH is a partial update, PUT is a full resource update  
-Delete - DELETE - /resources/:id  
+Create - POST   - /resources
+Read   - GET    - /resources/:id
+Update - PATCH  - /resources/:id  *PATCH is a partial update, PUT is a full resource update
+Delete - DELETE - /resources/:id
 
 #### Middleware Patterns
-Request Data validation and Middleware Flow Control -   [tjmehta/dat-middleware](https://github.com/tjmehta/dat-middleware)  
-Middleware Flow Control - [tjmehta/middleware-flow](https://github.com/tjmehta/middleware-flow)  
-Middlewares of models are autogenerated for you  
-* Mongoose Models - /lib/middlewares/mongo/index.js -   [tjmehta/mongooseware](https://github.com/tjmehta/mongooseware)  
-* Class Models - /lib/middlewares/apis/index.js [tjmehta/middlewarize](https://github.com/tjmehta/middlewarize)   
-Sharing the request object as a common context between middlewares allows us to make  
-asyncronous code look syncronous and avoid "callback hell"  
+
+Request Data validation and Middleware Flow Control -   [tjmehta/dat-middleware](https://github.com/tjmehta/dat-middleware)
+Middleware Flow Control - [tjmehta/middleware-flow](https://github.com/tjmehta/middleware-flow)
+Middlewares of models are autogenerated for you
+* Mongoose Models - /lib/middlewares/mongo/index.js -   [tjmehta/mongooseware](https://github.com/tjmehta/mongooseware)
+* Class Models - /lib/middlewares/apis/index.js [tjmehta/middlewarize](https://github.com/tjmehta/middlewarize)
+Sharing the request object as a common context between middlewares allows us to make
+asynchronous code look synchronous and avoid "callback hell"
+
 
 #### Boom for Http Errors
-Nice Http Error library - [spumko/boom](https://github.com/spumko/boom)
+Nice Http Error library - [hapijs/boom](https://github.com/hapijs/boom)
 
 
 
 Resource Overview
 =================
 Mongo Schemas - /lib/models/mongo/schemas/*.js
 
-Configs - Are a way of forking Infrastructure Code of a Project's Components
-
-Components - are application components. Ex: frontend-server, api-server, database
-* Infrastructure code - environment definition code
-* Application code - node.js code or etc. (github)
-
-Component Versions - a snapshot of infrastructure code version and application code version
+Context Versions - a snapshot of infrastructure code version and application code version
 * Dockerfile v0.1.0 and api-server v0.1.0
 * Can be built on unbuilt
 
@@ -107,11 +103,6 @@ npm run client-version # this will update the client's version to the latest in
 ```
 Models:
 
-projects (full blown project - that has multiple components)
- - environments (subdoc)
-  - builds    (collection)
-   - versions (collection) [redis v0.7, api v0.8, mongo v2.7]
-
 
 A context represents a project context (like redis)
 A version is a version of a particular context (build files, github commitHash)
@@ -144,5 +135,4 @@ Instance Page - /project/anandkumar/filibuster/master/build/:id (just like our c
  - create an instance from a build (create containers for all build images (versions))
 ```
 
-![Magic](https://s3.amazonaws.com/uploads.hipchat.com/31372/651154/nARA3Q63eW1j5WV/2014-07-04-14-45-39%20%281%29.png)
-
+![Magic](https://s3.amazonaws.com/uploads.hipchat.com/31372/651154/nARA3Q63eW1j5WV/2014-07-04-14-45-39%20%281%29.png)

lib/routes/builds.js

@@ -37,6 +37,8 @@ var findBuild = flow.series(
     me.isModerator));
 
 /** Create a build
+ *  @param {Object} body.owner build owner
+ *  @param [String] body.contextVersions array with one context version id.
  *  @returns [Build, ...]
  *  @event POST /builds/
  *  @memberof module:rest/builds */
@@ -175,7 +177,7 @@ app.post('/builds/:id/actions/copy',
   mw.res.json('build'));
 
 /** Build a build
- *  @param id buildId of the build to build (say that ten times fast)
+ *  @param id buildId of the build to build
  *  @returns Build
  *  @event GET /builds/
  *  @memberof module:rest/builds */