Add get/list/cancel docs

README.md

@@ -9,8 +9,12 @@ and some other logging and metadata.
 The schema and APIs is defined [here](./task_execution.proto) in [protocol buffers](https://developers.google.com/protocol-buffers/). Clients may use JSON and REST to communicate
 with a service implementing the TES API.
 
-Here's an example task message, defining a task which calculates
-an MD5 checksum on an input file and uploads output:
+
+Create a task
+---------------------------------
+
+Here's an example of a complete task message, defining a task which calculates
+an MD5 checksum on an input file and uploads the output:
 ```JSON
 {
     "name":        "MD5 example",
@@ -52,12 +56,95 @@ an MD5 checksum on an input file and uploads output:
 }
 ```
 
-This message would be submitted via HTTP Post to `/v1/tasks`.  
-The return value is a task ID:
+A minimal version of the same task, including only the required fields looks like:
 ```JSON
-{ "id": "6E57CA6B-0BC7-44FB-BA2C-0CBFEC629C63" }
+{
+    "inputs": [
+      {
+        "url":  "/path/to/input_file",
+        "path": "/container/input",
+      }
+    ],
+    "outputs" : [
+      {
+        "url" :  "/path/to/output_file",
+        "path" : "/container/output",
+      }
+    ],
+    "executors" : [
+      {
+        "image_name" : "ubuntu",
+        "cmd" : ["md5sum", "/container/input"],
+        "stdout" : "/container/output",
+      }
+    ]
+}
+```
+
+To create the task, send an HTTP POST request:
+```HTTP
+POST /v1/tasks
+
+{ "id": "task-1234" }
 ```
 
-Then, the task and logs may be retrieve with a HTTP GET.  
-`GET /v1/tasks/6E57CA6B-0BC7-44FB-BA2C-0CBFEC629C63
-`
+The return value is a task ID.
+
+
+Get a task
+--------------------------------
+
+To get a task by ID:
+
+```HTTP
+GET /v1/tasks/task-1234
+
+{ "id": "task-1234", "state": "RUNNING" }
+```
+
+The return value will be a minimal description of the task state.
+
+To get more information, you can change the task view using the `view` URL query parameter.  
+
+The `basic` view will include all task fields except a few which might be
+large strings (stdout/err logging, input parameter contents).
+
+```HTTP
+GET /v1/tasks/task-1234?view=BASIC
+
+{ "id": "task-1234", "state": "RUNNING", "name": "MD5 example", etc... }
+```
+
+The `full` view includes stdout/err logs and full input parameters:
+
+```HTTP
+GET /v1/tasks/task-1234?view=FULL
+
+{ "id": "task-1234", "state": "RUNNING", "name": "MD5 example",
+  "logs": [{ "stdout": "stdout content..." }], etc... }
+```
+
+List tasks
+------------------------------------
+
+To list tasks:
+
+```HTTP
+GET /v1/tasks
+
+{ "tasks": [{ "id": "task-1234", "state": "RUNNING"}, etc...] }
+```
+
+Similar to getting a task by ID, you may change the task view:
+```HTTP
+GET /v1/tasks?view=BASIC
+```
+
+
+Cancel a task
+-------------------------------------
+
+To cancel a task, send an HTTP POST to the cancel endpoint:
+```HTTP
+POST /v1/tasks/task-1234:cancel
+```