API definitions and docs update (#457)

* fix: using bolt config/header update now overwrites

* api definitions and doc updates

* merge docs

docs/README.md

@@ -7,6 +7,7 @@
 If you are a developer using IronFunctions through the API, this section is for you.
 
 * [Quickstart](https://github.com/iron-io/functions#quickstart)
+* [Definitions](definitions.md)
 * [fn (CLI Tool)](/fn/README.md)
 * [Writing functions](writing.md)
 * [Writing Lambda functions](lambda/create.md)
@@ -16,7 +17,6 @@ If you are a developer using IronFunctions through the API, this section is for
 * [API Reference](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/iron-io/functions/master/docs/swagger.yml)
 * [Hot containers](hot-containers.md)
 
-
 ## For Operators
 
 If you are operating IronFunctions, this section is for you.

docs/apps.md

@@ -1,35 +0,0 @@
-# Applications
-
-Applications are the top level object that groups routes together to create an API.
-
-## App level configuration
-
-When creating or updating an app, you can pass in a map of config variables.
-
-`config` is a map of values passed to the route runtime in the form of
-environment variables.
-
-Note: Route level configuration overrides app level configuration.
-
-```sh
-fn apps create --config k1=v1 --config k2=v2 myapp
-```
-
-Or using a cURL:
-
-```sh
-curl -H "Content-Type: application/json" -X POST -d '{
-    "app": {
-        "name":"myapp-curl",
-        "config": {
-            "k1": "v1",
-            "k2": "v2"
-        }
-    }
-}' http://localhost:8080/v1/apps
-```
-
-## Notes
-
-App names are immutable. When doing `PUT` calls, keep in mind that although you
-are able to update an app's configuration set, you cannot really rename it.

docs/definitions.md

@@ -0,0 +1,153 @@
+# API Definitions
+
+# Applications
+
+Applications are the top level object that groups routes together to create an API.
+
+### Creating applications
+
+Using `fn`:
+
+```sh
+fn apps create --config k1=v1 --config k2=v2 myapp
+```
+
+Or using a cURL:
+
+```sh
+curl -H "Content-Type: application/json" -X POST -d '{
+    "app": {
+        "name":"myapp-curl",
+        "config": {
+            "k1": "v1",
+            "k2": "v2"
+        }
+    }
+}' http://localhost:8080/v1/apps
+```
+
+### App Example
+
+```json
+{
+    "name": "myapp",
+    "myconfig": "config"
+}
+```
+
+### Properties
+
+#### name (string)
+
+`name` is a property that references an unique app. 
+
+App names are immutable. When updating apps with `PATCH` requests, keep in mind that although you
+are able to update an app's configuration set, you cannot really rename it.
+
+#### config (object)
+
+`config` is a map of values passed to the route runtime in the form of
+environment variables. 
+
+Note: Route level configuration overrides app level configuration.
+
+## Routes
+
+### Creating routes
+
+Using `fn`:
+
+```sh
+fn routes create --config k1=v1 --config k2=v2 myapp /path image
+```
+
+Or using a cURL:
+
+```sh
+curl -H "Content-Type: application/json" -X POST -d '{
+    "app": {
+        "path": "/path",
+        "image": "image",
+        "config": {
+            "k1": "v1",
+            "k2": "v2"
+        }
+    }
+}' http://localhost:8080/v1/apps/myapp/routes
+```
+
+### Route Example
+```json
+{
+    "path": "/hello",
+    "image": "iron/hello",
+    "type": "sync",
+    "memory": 128,
+    "config": {
+        "key": "value",
+        "key2": "value2",
+        "keyN": "valueN",
+    },
+    "headers": {
+        "content-type": [
+            "text/plain"
+        ]
+    }
+}
+```
+
+### Properties
+
+#### path (string)
+
+Represents a unique `route` in the API and is identified by the property `path` and `app`.
+
+Every `route` belongs to an `app`.
+
+Note: Route paths are immutable. If you need to change them, the appropriate approach
+is to add a new route with the modified path.
+
+#### image (string)
+
+`image` is the name or registry URL that references to a valid container image located locally or in a remote registry (if provided any registry address).
+
+If no registry is provided and image is not available locally the API will try pull it from a default public registry.
+
+#### type (string)
+
+Options: `sync` and `async`
+
+`type` is defines how the function will be executed. If type is `sync` the request will be hold until the result is ready and flushed.
+
+In `async` functions the request will be ended with a `call_id` and the function will be executed in the background.
+
+#### memory (number)
+
+`memory` defines the amount of memory (in megabytes) required to run this function.
+
+#### config (object of string values)
+
+`config` is a map of values passed to the route runtime in the form of
+environment variables.
+
+Note: Route level configuration overrides app level configuration.
+
+#### headers (object of array of string)
+
+`header` is a set of headers that will be sent in the function execution response. The header value is an array of strings.
+
+#### format (string)
+
+`format` defines if the function is running or not in `hot container` mode.
+
+To define the function execution as `hot container` you set it as one of the following formats:
+
+- `"http"`
+
+### 'Hot Container' Only Properties
+
+This properties are only used if the function is in `hot container` mode
+
+#### max_concurrency (string)
+
+This property defines the maximum amount of concurrent hot containers instances the function should have (per IronFunction node). 

docs/function-file.md

@@ -18,6 +18,9 @@ config:
   key: value
   key2: value2
   keyN: valueN
+headers:
+  content-type:
+   - text/plain
 build:
 - make
 - make test

docs/routes.md

@@ -1,21 +0,0 @@
-# Routes
-
-Each application has several functions represented through routes.
-
-## Route level configuration
-
-When creating or updating an app, you can pass in a map of config variables.
-
-`config` is a map of values passed to the route runtime in the form of
-environment variables.
-
-Note: Route level configuration overrides app level configuration.
-
-```sh
-fn routes create --config k1=v1 --config k2=v2 myapp /path image
-```
-
-## Notes
-
-Route paths are immutable. If you need to change them, the appropriate approach
-is to add a new route with the modified path.