Cleaning up docs

docs/README.md

@@ -7,6 +7,7 @@
 If you are a developer using Oracle Functions through the API, this section is for you.
 
 * [Quickstart](https://github.com/treeder/functions#quickstart)
+* [Usage](usage.md)
 * [Definitions](definitions.md)
 * [fn (CLI Tool)](/fn/README.md)
 * [Writing functions](writing.md)

docs/serverless.md

@@ -0,0 +1,35 @@
+# What is Serverless/FaaS?
+
+Serverless is a new paradigm in computing that enables simplicity, efficiency and scalability for both developers
+and operators. It's important to distinguish the two, because the benefits differ:
+
+## Benefits for developers
+
+The main benefits that most people refer to are on the developer side and they include:
+
+* No servers to manage (serverless) -- you just upload your code and the platform deals with the infrastructure
+* Super simple coding -- no more monoliths! Just simple little bits of code
+* Pay by the milliseconds your code is executing -- unlike a typical application that runs 24/7, and you're paying
+  24/7, functions only run when needed
+
+Since you'll be running Oracle Functions yourself, the paying part may not apply, but it does apply to
+cost savings on your infrastructure bills as you'll read below.
+
+## Benefits for operators
+
+If you will be operating Oracle Functions (the person who has to manage the servers behind the serverless),
+then the benefits are different, but related.
+
+* Extremely efficient use of resources
+  * Unlike an app/API/microservice that consumes resources 24/7 whether they
+    are in use or not, functions are time sliced across your infrastructure and only consume resources while they are
+    actually doing something
+* Easy to manage and scale
+  * Single system for code written in any language or any technology
+  * Single system to monitor
+  * Scaling is the same for all functions, you don't scale each app independently
+  * Scaling is simply adding more Oracle Functions nodes
+
+There is a lot more reading you can do on the topic, just search for 
+["what is serverless"](https://www.google.com/webhp?sourceid=chrome-instant&ion=1&espv=2&ie=UTF-8#q=what%20is%20serverless)
+and you'll find plenty of information.

docs/usage.md

@@ -0,0 +1,127 @@
+# Detailed Usage
+
+This is a more detailed explanation of the main commands you'll use in Oracle Functions as a developer.
+
+### Create an Application
+
+An application is essentially a grouping of functions, that put together, form an API. Here's how to create an app.
+
+```sh
+fn apps create myapp
+```
+
+Or using a cURL:
+
+```sh
+curl -H "Content-Type: application/json" -X POST -d '{
+    "app": { "name":"myapp" }
+}' http://localhost:8080/v1/apps
+```
+
+[More on apps](docs/apps.md).
+
+Now that we have an app, we can route endpoints to functions.
+
+### Add a Route
+
+A route is a way to define a path in your application that maps to a function. In this example, we'll map
+`/hello` to a simple `Hello World!` function called `treeder/hello` which is a function we already made that you
+can use -- yes, you can share functions! The source code for this function is in the [examples directory](examples/hello/go).
+You can read more about [writing your own functions here](docs/writing.md).
+
+```sh
+fn routes create myapp /hello -i treeder/hello
+```
+
+Or using cURL:
+
+```sh
+curl -H "Content-Type: application/json" -X POST -d '{
+    "route": {
+        "path":"/hello",
+        "image":"treeder/hello"
+    }
+}' http://localhost:8080/v1/apps/myapp/routes
+```
+
+[More on routes](docs/routes.md).
+
+### Calling your Function
+
+Calling your function is as simple as requesting a URL. Each app has its own namespace and each route mapped to the app.
+The app `myapp` that we created above along with the `/hello` route we added would be called via the following
+URL: http://localhost:8080/r/myapp/hello
+
+Either surf to it in your browser or use `fn`:
+
+```sh
+fn call myapp /hello
+```
+
+Or using a cURL:
+
+```sh
+curl http://localhost:8080/r/myapp/hello
+```
+
+### Passing data into a function
+
+Your function will get the body of the HTTP request via STDIN, and the headers of the request will be passed in
+as env vars. You can test a function with the CLI tool:
+
+```sh
+echo '{"name":"Johnny"}' | fn call myapp /hello
+```
+
+Or using cURL:
+
+```sh
+curl -H "Content-Type: application/json" -X POST -d '{
+    "name":"Johnny"
+}' http://localhost:8080/r/myapp/hello
+```
+
+You should see it say `Hello Johnny!` now instead of `Hello World!`.
+
+### Add an asynchronous function
+
+Oracle Functions supports synchronous function calls like we just tried above, and asynchronous for background processing.
+
+Asynchronous function calls are great for tasks that are CPU heavy or take more than a few seconds to complete.
+For instance, image processing, video processing, data processing, ETL, etc.
+Architecturally, the main difference between synchronous and asynchronous is that requests
+to asynchronous functions are put in a queue and executed on upon resource availability so that they do not interfere with the fast synchronous responses required for an API.
+Also, since it uses a message queue, you can queue up millions of function calls without worrying about capacity as requests will
+just be queued up and run at some point in the future.
+
+To add an asynchronous function, create another route with the `"type":"async"`, for example:
+
+```sh
+curl -H "Content-Type: application/json" -X POST -d '{
+    "route": {
+        "type": "async",
+        "path":"/hello-async",
+        "image":"treeder/hello"
+    }
+}' http://localhost:8080/v1/apps/myapp/routes
+```
+
+Now if you request this route:
+
+```sh
+curl -H "Content-Type: application/json" -X POST -d '{
+    "name":"Johnny"
+}' http://localhost:8080/r/myapp/hello-async
+```
+
+You will get a `call_id` in the response:
+
+```json
+{"call_id":"572415fd-e26e-542b-846f-f1f5870034f2"}
+```
+
+If you watch the logs, you will see the function actually runs in the background:
+
+![async log](docs/assets/async-log.png)
+
+Read more on [logging](docs/logging.md).