Clarify use and purpose of templates in this repo

[alexellis]

Clarifies expectations for usage of the templates in this
repo along with an update to the python3-flask template so that
it provides a better upgrade path.

Examples added for python3-flask to show how to return a HTTP
error or status code.

Signed-off-by: Alex Ellis (OpenFaaS Ltd) alexellis2@gmail.com

[alexellis]

For a semblance of consistency -> https://github.com/openfaas/templates/blob/master/template/node12/index.js#L11

[alexellis]

To enable easier migration from the python3 template

[LucasRoesler]

perhaps this would be useful here https://docs.python.org/3/distutils/apiref.html#distutils.util.strtobool

Convert a string representation of truth to true (1) or false (0).

True values are y, yes, t, true, on and 1; false values are n, no, f, false, off and 0. Raises ValueError if val is anything else.

[alexellis]

Yes sounds reasonable to me

[Jeff-Lowrey]

There are several places in the README where a 201 is returned instead of a 200.

Is there a specific reason for this?

For example

Successful response status code and string response body

python
def handle(event, context):
return {
"statusCode": 201,
"body": "Object successfully created"
}

[alexellis]

Yes - to show that you can alter the HTTP status code @Jeff-Lowrey

[Jeff-Lowrey]

@alexellis Ok, here's the bit that itches at me.

The two examples for custom status codes and response bodies in the example usage for the -http templates seem a little... I dunno - off balance?

The first one shows a standard response code and (I guess json counts as?) a custom response body.
The second one shows a custom response code and (I guess plain text counts as?) a standard response body.

I'd be happier, I think, if the first one said

Successful response status code and custom JSON response body

and the second said

Custom response status code and standard string response body

Or otherwise something to emphasize the point of the two different examples. One is a custom body and one is a custom response code.

I'm sure I'm way over thinking this.

current:

Successful response status code and JSON response body

def handle(event, context):
    return {
        "statusCode": 200,
        "body": {
            "key": "value"
        }
    }

versus

Successful response status code and string response body

def handle(event, context):
    return {
        "statusCode": 201,
        "body": "Object successfully created"
    }

[alexellis]

@Jeff-Lowrey I'm sorry I don't quite get what point you're trying to make? Is it that you would like to see another HTTP code other than 201 used in examples? What would that add?

[viveksyngh]

I guess there is a typo, it is waitress not witness

[Jeff-Lowrey]

@Jeff-Lowrey I'm sorry I don't quite get what point you're trying to make? Is it that you would like to see another HTTP code other than 201 used in examples? What would that add?

@alexellis I'm trying to clarify the descriptive text of each example in the -http section to show why one has a 201 and one has a 200. I know that the intent is to show custom return codes and custom message bodies.

It's just, at least to me, not glaringly obvious from the descriptive text what each example is showing - it's only really clear when I read the code. Without explicitly noticing the result code, the descriptions say that example one has a JSON reply body and example two has a string reply body.

The text in the JSON reply body does say something that matches the 201. But, again, this is not glaringly obvious from the description of the example.

Maybe I'm over thinking this. But it did confuse me at first reading even though I know about setting the statusCode field. So it might be more confusing to someone that doesn't know about using the status code.

I don't think this is a "must fix" issue. Just something that popped out.