Merge pull request #17 from CesarGallego/master

Spec changes

spec/README.md

@@ -98,7 +98,8 @@ TODO: Intro to Architecture
 
 ### Core Concepts
 
-In this section we are going to define several concepts that will be used frequently throughout the spec.
+In this section we are going to define several concepts that will be used 
+frequently throughout the spec.
 
 
 #### `entrypoint`
@@ -126,15 +127,18 @@ whole lifetime of the server.
 
 ## Design Principles
 
+* Kapow! implementations should follow a general principle of robustness: be 
+  conservative in what you do, be liberal in what you accept from others.
 * We reuse conventions of well-established software projects, such as Docker.
 * All requests and responses will leverage JSON as the data encoding method.
-* The API calls responses will have two distinct parts:
+* The API calls responses have several parts:
   * The HTTP status code (e.g., `400`, which is a bad request).  The target
     audience of this information is the client code.  The client can thus use
     this information to control the program flow.
   * The HTTP reason phrase.  The target audience in this case is the human
     operating the client.  The human can use this information to make a
     decision on how to proceed.
+  * The body is optional
 * All successful API calls will return a representation of the *final* state
   attained by the objects which have been addressed (either requested, set or
   deleted).
@@ -176,7 +180,8 @@ respond to an external event (e.g.  an incoming HTTP request).
 
 #### List routes
 
-Returns JSON data about the current routes.
+Returns JSON with all the data about the current routes. Be aware that the command
+field must be a json scaped string.
 
 * **URL**: `/routes`
 * **Method**: `GET`
@@ -204,12 +209,14 @@ Returns JSON data about the current routes.
     ]
     ```
 * **Sample Call**: `$ curl $KAPOW_URL/routes`
-* **Notes**: Currently all routes are returned; in the future, a filter may be accepted.
+* **Notes**: Currently all routes are returned; in the future, a filter may be 
+  accepted.
 
 
 #### Append route
 
-Accepts JSON data that defines a new route to be appended to the current routes.  A new id is created for the appended route so it can be referenced later.
+Accepts JSON data that defines a new route to be appended to the current routes.
+A new id is created for the appended route so it can be referenced later.
 
 * **URL**: `/routes`
 * **Method**: `POST`
@@ -239,19 +246,7 @@ Accepts JSON data that defines a new route to be appended to the current routes.
     ```
 * **Error Responses**:
   * **Code**: `400 Malformed JSON`
-  * **Code**: `422 Invalid Data Type`
+  * **Code**: `422 Invalid Route`
-  * **Code**: `422 Invalid Route Spec`
-  * **Code**: `422 Missing Mandatory Field`<br />
-    **Header**: `Content-Type: application/json`<br />
-    **Content**:<br />
-    ```json
-    {
-      "missing_mandatory_fields": [
-        "url_pattern",
-        "command"
-      ]
-    }
-    ```
 * **Sample Call**:<br />
     ```sh
     $ curl -X POST --data-binary @- $KAPOW_URL/routes <<EOF
@@ -273,7 +268,8 @@ Accepts JSON data that defines a new route to be appended to the current routes.
 #### Insert a route
 
   Accepts JSON data that defines a new route to be inserted at the specified
-  index to the current routes.  A new id is created for the inserted route so it can be referenced later.
+  index to the current routes.  A new id is created for the inserted route so it
+  can be referenced later.
 
 * **URL**: `/routes`
 * **Method**: `PUT`
@@ -303,20 +299,7 @@ Accepts JSON data that defines a new route to be appended to the current routes.
     ```
 * **Error Responses**:
   * **Code**: `400 Malformed JSON`
-  * **Code**: `422 Invalid Data Type`
+  * **Code**: `422 Invalid Route`
-  * **Code**: `422 Invalid Route Spec`
-  * **Code**: `422 Missing Mandatory Field`<br />
-    **Header**: `Content-Type: application/json`<br />
-    **Content**:<br />
-    ```json
-    {
-      "missing_mandatory_fields": [
-        "url_pattern",
-        "command"
-      ]
-    }
-    ```
-  * **Code**: `422 Invalid Index Type`
 * **Sample Call**:<br />
     ```sh
     $ curl -X PUT --data-binary @- $KAPOW_URL/routes <<EOF`
@@ -452,11 +435,13 @@ following resource paths:
   - Returned Value: `foo`
   - Comment: That would provide read-only access to the request URL parameter `q`.
 - Obtain the `Content-Type` header of the request.
-  - Scenario: A POST request with a JSON body and the header `Content-Type` set to `application/json`.
+  - Scenario: A POST request with a JSON body and the header `Content-Type` set 
+    to `application/json`.
   - Key: `/request/headers/Content-Type`
   - Access: Read-Only
   - Returned Value: `application/json`
-  - Comment: That would provide read-only access to the value of the request header `Content-Type`.
+  - Comment: That would provide read-only access to the value of the request 
+    header `Content-Type`.
 - Read a field from a form.
   - Scenario: A request generated by submitting this form:<br />
     ```html
@@ -471,21 +456,24 @@ following resource paths:
   - Key: `/request/form/firstname`
   - Access: Read-Only
   - Returned Value: `Jane`
-  - Comment: That would provide read-only access to the value of the field `firstname` of the form.
+  - Comment: That would provide read-only access to the value of the field 
+    `firstname` of the form.
 - Set the response status code.
   - Scenario: A request is being attended.
   - Key: `/response/status`
   - Access: Write-Only
   - Acceptable Value: A 3-digit integer.  Must match `[0-9]{3}`.
   - Default Value: `200`
-  - Comment: It is customary to use the HTTP status code as defined at [https://www.w3.org/Protocols/rfc2616/rfc2616-sec6.html#sec6.1.1](RFC2616).
+  - Comment: It is customary to use the HTTP status code as defined at
+    [https://www.w3.org/Protocols/rfc2616/rfc2616-sec6.html#sec6.1.1](RFC2616).
 - Set the response body.
   - Scenario: A request is being attended.
   - Key: `/response/body`
   - Access: Write-Only
   - Acceptable Value: Any string of bytes.
   - Default Value: N/A
-  - Comment: For media types other than `application/octet-stream` you should specify the appropiate `Content-Type` header.
+  - Comment: For media types other than `application/octet-stream` you should 
+    specify the appropiate `Content-Type` header.
 
 **Note**: Parameters under `request` are read-only and, conversely, parameters under
 `response` are write-only.
@@ -493,11 +481,13 @@ following resource paths:
 
 #### Get handler resource
 
-Returns the value of the requested resource path, or an error if the resource path doesn't exist or is invalid.
+Returns the value of the requested resource path, or an error if the resource 
+path doesn't exist or is invalid.
 
 * **URL**: `/handlers/{:handler_id}{:resource_path}`
 * **Method**: `GET`
-* **URL Params**: FIXME: We think that here should be options to cook the value in some way, or get it raw.
+* **URL Params**: FIXME: We think that here should be options to cook the value 
+  in some way, or get it raw.
 * **Success Responses**:
   * **Code**: `200 OK`<br />
     **Header**: `Content-Type: application/octet-stream`<br />
@@ -517,22 +507,18 @@ Returns the value of the requested resource path, or an error if the resource pa
 
 * **URL**: `/handlers/{:handler_id}{:resource_path}`
 * **Method**: `PUT`
-* **URL Params**: FIXME: We think that here should be options to cook the value in some way, or pass it raw.
+* **URL Params**: FIXME: We think that here should be options to cook the value 
+  in some way, or pass it raw.
 * **Data Params**: Binary payload.
 * **Success Responses**:
   * **Code**: `200 OK`
 * **Error Responses**:
-  * **Code**: `400 Invalid Payload`
+  * **Code**: `400 Invalid Resource`
-  * **Code**: `400 Invalid Resource Path`<br />
+  * **Code**: `404 Not Found`
-    **Notes**: Check the list of valid resource paths at the top of this section.
-  * **Code**: `404 Handler Not Found`
-  * **Code**: `404 Name Not Found`<br />
-    **Notes**: Although the resource path is correct, no such name is present in the request.  For instance, `/request/headers/Foo`, when no `Foo` header is not present in the request.
 * **Sample Call**:<br />
   ```sh
   $ curl -X --data-binary '<h1>Hello!</h1>' PUT /handlers/$KAPOW_HANDLER_ID/response/body
   ```
-* **Notes**:
 
 
 ## Usage Example