Dark-Alex-17/kapow
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #17 from CesarGallego/master

Browse Source 
Spec changes
This commit is contained in:
Roberto Abdelkader Martínez Pérez
2019-08-21 12:05:37 +02:00
committed by GitHub
parent 8040cb5b3b 3a8adb19f7
commit 9ae748e5c1
1 changed files with 34 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files
spec/README.md
+34 -48
View File
@@ -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 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 Route`
* **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 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`
* **Code**: `422 Invalid Route`
* **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 Path`<br />
**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.
* **Code**: `400 Invalid Resource`
* **Code**: `404 Not Found`
* **Sample Call**:<br />
```sh
$ curl -X --data-binary '<h1>Hello!</h1>' PUT /handlers/$KAPOW_HANDLER_ID/response/body
```
* **Notes**:
## Usage Example