From a7ea97d1d56fa762b65a2fea71846d6166660584 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?C=C3=A9sar=20Gallego=20Rodr=C3=ADguez?= Date: Wed, 21 Aug 2019 09:42:21 +0200 Subject: [PATCH 1/8] Explicit format in command. --- spec/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/spec/README.md b/spec/README.md index 6fc69ec..a8928b9 100644 --- a/spec/README.md +++ b/spec/README.md @@ -176,7 +176,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 data about the current routes. Be aware that the command +field must be a json scaped string. * **URL**: `/routes` * **Method**: `GET` From c834bd44479283dbb3438ba422fbb06ea094af4c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?C=C3=A9sar=20Gallego=20Rodr=C3=ADguez?= Date: Wed, 21 Aug 2019 09:57:44 +0200 Subject: [PATCH 2/8] Robustness principle and optional body. --- spec/README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/spec/README.md b/spec/README.md index a8928b9..7fd5436 100644 --- a/spec/README.md +++ b/spec/README.md @@ -126,15 +126,18 @@ whole lifetime of the server. ## Design Principles +* TCP 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 will 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 it's 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). From 2eaac52a034355f42e370878659ed17d92f08f2e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?C=C3=A9sar=20Gallego=20Rodr=C3=ADguez?= Date: Wed, 21 Aug 2019 10:15:55 +0200 Subject: [PATCH 3/8] Less errors, less complex. --- spec/README.md | 34 ++-------------------------------- 1 file changed, 2 insertions(+), 32 deletions(-) diff --git a/spec/README.md b/spec/README.md index 7fd5436..6f98980 100644 --- a/spec/README.md +++ b/spec/README.md @@ -243,19 +243,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 Spec` - * **Code**: `422 Missing Mandatory Field`
- **Header**: `Content-Type: application/json`
- **Content**:
- ```json - { - "missing_mandatory_fields": [ - "url_pattern", - "command" - ] - } - ``` * **Sample Call**:
```sh $ curl -X POST --data-binary @- $KAPOW_URL/routes < - **Header**: `Content-Type: application/json`
- **Content**:
- ```json - { - "missing_mandatory_fields": [ - "url_pattern", - "command" - ] - } - ``` - * **Code**: `422 Invalid Index Type` * **Sample Call**:
```sh $ curl -X PUT --data-binary @- $KAPOW_URL/routes < - **Notes**: Check the list of valid resource paths at the top of this section. - * **Code**: `404 Handler Not Found` - * **Code**: `404 Name Not Found`
- **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. + * **Code**: `400 Invalid Resource` + * **Code**: `404 Not Found` * **Sample Call**:
```sh $ curl -X --data-binary '

Hello!

' PUT /handlers/$KAPOW_HANDLER_ID/response/body ``` -* **Notes**: ## Usage Example From d4bcd4cae637fe271131f7f0979996caa56187d9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?C=C3=A9sar=20Gallego=20Rodr=C3=ADguez?= Date: Wed, 21 Aug 2019 10:21:16 +0200 Subject: [PATCH 4/8] Correct line breaks. --- spec/README.md | 36 ++++++++++++++++++++++++------------ 1 file changed, 24 insertions(+), 12 deletions(-) diff --git a/spec/README.md b/spec/README.md index 6f98980..494b8a9 100644 --- a/spec/README.md +++ b/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` @@ -208,12 +209,14 @@ field must be a json scaped string. ] ``` * **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` @@ -265,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` @@ -431,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:
```html @@ -450,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. @@ -472,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`
**Header**: `Content-Type: application/octet-stream`
@@ -496,7 +507,8 @@ 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` From d9f247cc17558143d11625a46f658fd5ebcd1fe1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?C=C3=A9sar=20Gallego=20Rodr=C3=ADguez?= Date: Wed, 21 Aug 2019 11:59:07 +0200 Subject: [PATCH 5/8] Update spec/README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit language fix Co-Authored-By: Roberto Abdelkader Martínez Pérez --- spec/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/README.md b/spec/README.md index 494b8a9..55acfe1 100644 --- a/spec/README.md +++ b/spec/README.md @@ -180,7 +180,7 @@ respond to an external event (e.g. an incoming HTTP request). #### List routes -Returns JSON with all data about the current routes. Be aware that the command +Returns JSON with all the data about the current routes. Be aware that the command field must be a json scaped string. * **URL**: `/routes` From 44287738f557b3a1cdbc69ae9a98027fe99fdd33 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?C=C3=A9sar=20Gallego=20Rodr=C3=ADguez?= Date: Wed, 21 Aug 2019 11:59:21 +0200 Subject: [PATCH 6/8] Update spec/README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit language fix Co-Authored-By: Roberto Abdelkader Martínez Pérez --- spec/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/README.md b/spec/README.md index 55acfe1..5859f4c 100644 --- a/spec/README.md +++ b/spec/README.md @@ -246,7 +246,7 @@ A new id is created for the appended route so it can be referenced later. ``` * **Error Responses**: * **Code**: `400 Malformed JSON` - * **Code**: `422 Invalid Route Spec` + * **Code**: `422 Invalid Route` * **Sample Call**:
```sh $ curl -X POST --data-binary @- $KAPOW_URL/routes < Date: Wed, 21 Aug 2019 11:59:32 +0200 Subject: [PATCH 7/8] Update spec/README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit language fix Co-Authored-By: Roberto Abdelkader Martínez Pérez --- spec/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/README.md b/spec/README.md index 5859f4c..c6bd550 100644 --- a/spec/README.md +++ b/spec/README.md @@ -299,7 +299,7 @@ A new id is created for the appended route so it can be referenced later. ``` * **Error Responses**: * **Code**: `400 Malformed JSON` - * **Code**: `422 Invalid Route Spec` + * **Code**: `422 Invalid Route` * **Sample Call**:
```sh $ curl -X PUT --data-binary @- $KAPOW_URL/routes < Date: Wed, 21 Aug 2019 12:01:08 +0200 Subject: [PATCH 8/8] Minor fixes on human words. Thanks-to: Nilp0inter --- spec/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/README.md b/spec/README.md index c6bd550..783aeaa 100644 --- a/spec/README.md +++ b/spec/README.md @@ -127,18 +127,18 @@ whole lifetime of the server. ## Design Principles -* TCP implementations should follow a general principle of robustness: be +* 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 several 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 it's optional + * 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).