Faas: Implement strict RESTful API

[imeoer]

Expected Behaviour

The API definition of gateway and provider should be more in line with the RESTful semantic specification.

Note: Do not change existing endpoints/routes - so we can maintain compatibility

Current Behaviour

// List of deployed functions.
GET /system/functions
-> 200 Ok

// Deploy a new function.
POST /system/functions
-> 200 Ok

// Remove a deployed function.
DELETE /system/functions
-> 200 Ok
-> 404 Not Found

// Invoke a deployed function.
POST /function/$name
-> 200 Ok
-> 404 Not Found
-> 500 Internal Server Error

// Invoke a deployed function asynchronously
POST /async-function/$name
-> 202 Accepted
-> 404 Not Found
-> 500 Internal Server Error

// Event-sink for AlertManager
POST /system/alert
-> 200 Ok
-> 500 Internal Server Error

Possible Solution

// List of deployed functions.
GET /system/functions
-> 200 Ok
-> 500 Internal Server Error

// Deploy a new function.
POST /system/functions
-> 201 Created
-> 400 Bad Request
-> 500 Internal Server Error
-> 503 Service Unavailable (FaaS Provider Unreachable)

// Remove a deployed function.
DELETE /system/functions/$name
-> 204 No Content
-> 400 Bad Request
-> 404 Not Found
-> 500 Internal Server Error

// Update a deployed function.
PUT /system/functions/$name
-> 200 Ok
-> 400 Bad Request
-> 404 Not Found
-> 500 Internal Server Error

// Invoke a deployed function.
ANY /function/$name
-> 400 Bad Request
-> 200 Ok
-> 404 Not Found
-> 500 Internal Server Error

// Invoke a deployed function asynchronously
ANY /async-function/$name
-> 400 Bad Request
-> 202 Accepted
-> 404 Not Found
-> 500 Internal Server Error

// Event-sink for AlertManager
POST /system/alert
-> 400 Bad Request
-> 200 Ok
-> 500 Internal Server Error

Would be updating gateway, provider, related test cases and Swagger definition.

[alexellis]

Can you do a current behaviour vs expected for this please? We also need to cover UPDATE function

[imeoer]

@alexellis Updated. where is the UPDATE definition in the Swagger doc?

[alexellis]

It is currently in progress in #208 @johnmccabe can you also update the Swagger when you have time?

[imeoer]

@alexellis I will try to update once have time.

[johnmccabe]

Derek add label: proposal

[alexellis]

How can a GET form a bad request in this instance?

// List of deployed functions.
GET /system/functions
-> 400 Bad Request
-> 200 Ok

[imeoer]

@alexellis Right, updated. :)

[alexellis]

Derek add label: hacktoberfest

[VitorFalcao]

@alexellis I would like to start contributing to the project and this seems to be a nice start. May I have it? And do you have any further instructions? Thank you.

[nullseed]

@VitorFalcao have you started work on this?

[VitorFalcao]

@nullseed I am currently familiarizing myself with the codebase and then I will implement it. If this is urgent and you want to solve it, then go ahead. If not, I would like to keep working on it, I find this project very interesting and would like to start contributing to it.

[nullseed]

@VitorFalcao I'll leave it to you then, feel free to run ideas by me here, I'm also interested in this issue.

[alexellis]

@nullseed this can be implemented on the faas-netes side too and faas-provider. Do you want to take that piece?

[alexellis]

Note: Do not change existing endpoints/routes - so we can maintain compatibility

[VitorFalcao]

@alexellis I would like to confirm what I would need to do. Basically: check every single route handler and set the w.WriteHeader(http.StatusOK) to the appropriate status, correct?

[nullseed]

@VitorFalcao there's also identifying error paths and returning the appropriate error codes when an error occurs. It would be great to add some tests around these endpoints changes too. If you like i will take a stab at this one and you can look at my PR and use it as a reference for contributing to faas-netes and faas-provider. @alexellis where would you like the tests adding, in this repo or certify-incubator?

[alexellis]

This is work @imeoer committed to do. @imeoer are you still wanting to do this or can someone else pick it up?

@VitorFalcao basically I think the idea was to include the function name as part of the URL. You could start there with a PR to the openfaas/faas-provider repo (do not modify the existing routes).

[imeoer]

@alexellis Sorry, I do not have time to do this now, hope someone else picks it up.

[alexellis]

Was it Harry Zhang that took over from you? Do you think he can pick it up?

[nullseed]

I'd like to continue work on this if no one else has started.

[alexellis]

@nullseed how far did you get with this? Do you still need more time to complete your changes?

cc/ @stefanprodan we spoke about this yesterday.

[stefanprodan]

I propose to start versioning the API. This way we can ensure backwards compatibility with the CLI.
In the past I've used go-chi middleware, it has a nice way of handling API versioning, an example can be found here https://github.com/go-chi/chi/blob/master/_examples/versions/main.go

[ivanayov]

@imeoer do you have any input/comments regarding the latest API?

[imeoer]

@ivanayov Haven't yet, We can refer to the API design of k8s or docker. ;)

[alexellis]

Derek close: lack of interest / activity from community