Define schema for handler output

[rafaelcaricio]

Define schema for handler output

[rafaelcaricio]

To cover most of the possible responses in APIs, the dictionary keys described bellow should be sufficient.

{
    "content": str,
    "json": Union[dict, List[dict]],
    "file": Union[IO[AnyStr], str],
    "redirect": str,
    "status": int,
    "headers": Dict[str, str]
}

Descriptions

Key	Type	Description
content	str	Body of HTTP request. No treatment/parsing of this value is done. The value is passed directly to the chosen framework.
json	Union[dict, List[dict]]	JSON value to be used in the body of the request. This is a shortcut to having the header "Content-Type: application/json" and serializing this value using the most common way done by the chosen framework.
file	Union[IO[AnyStr], str]	Data to be returned as byte stream. This is a shortcut for having the header "Content-Type: application/octet-stream". Uses the most common way to stream files with the chosen framework.
redirect	str	The path or full URL to be redirected. This is a shortcut for having the header "Location:" with HTTP status 301.
status	int	The HTTP status code to be used in the response. This value overrides any shortcut default status code.
headers	Dict[str, str]	The HTTP headers to be used in the response. This value is merged with the shortcut values with priority.

Examples

We have exposed here some examples of using different configurations of the dict we've defined above to describe the HTTP response of API handlers. The actual HTTP response value generated will vary depending on the framework chosen as runtime. The examples are a minimal illustration of what to expect to be the HTTP response.

"content" key example

When it's desired to return a "Hello world!" string with status 200:

def say_hello(params):
    return {"content": "Hello world!"}

Results in the HTTP response similar to:

HTTP/1.1 200 OK
Content-Type: text/plain

Hello world!

"json" key example

It's desired to return an JSON response with status 201:

def create(params):
    data = {
        "id": "uhHuehuE",
        "value": "something"
    }
    return {"json": data, "status": 201}

The HTTP response generated will be similar to:

HTTP/1.1 201 Created
Content-Type: application/json

{"id":"uhHuehuE","value":"something"}

[rafaelcaricio]

Done. Basic support is done.