OpenAPI and REST services.

Question

Yay for first draft Going to chew on this for a while and see if I can t beautify it a bit Not sure how much is changing with the next firmware but I can see some areas to simplify Main one is removing the `opt` query param and use HTTP Methods `GET` returns the current state get power|nodeinfo `PUT` updates the node state set power etc `POST` perform an operation set bulk data or upload data network reset firmware update Second is make the routes more deterministic by moving the `type` query param into a path Example ```bash BMC USB State curl X GET 127 0 0 1 api bmc usb Array response curl X GET 127 0 0 1 api bmc info curl X GET 127 0 0 1 api bmc power Single node response curl X GET 127 0 0 1 api bmc node 1 info Set Power using Array curl X POST d 1 1 0 0 127 0 0 1 api bmc power Individual control curl X PUT d 1 127 0 0 1 api bmc node 1 power ``` https github com PhearZero turing pi api blob main v1 0 1 oas yml

destomes · Answer

Depending on how easy it is to parse the request route on the BMC server we could add the node ID to the routes to make them act on resources toggles on that node ` api bmc 1 info` etc instead of passing query parameters hah totally missed the single node resource route you have

destomes · Answer

I would also rather have a larger object returned on a resource get request and potentially just use patch requests to toggle the state of those node resources by sending just the properties I m interested in Like the power or usb mode or others in the future Also providing a way to offload generic state to the BMC that different frontends could use would be nice

phearzero · Answer

Yea there is a lot that can be added The root levels are usually good places to compose all of state Request ```bash curl X GET 127 0 0 1 api bmc node 1 ``` Response ```json info unkown power 1 usb 0 ``` Patch ```bash curl X PATCH d power 0 127 0 0 1 api bmc node 1 ``` This can go up the root to things like ` api bmc` and possibly hide some child data with a query like ` include all=true` ```json usb 0 other node1 info unkown power 1 usb 0 node2 info unkown power 1 usb 0 ```

phearzero · Answer

Here is a v1 0 1 CE interface for TS JS Going to push it up to npm later today https github com PhearZero turing pi js blob main index ts

destomes · Answer

Did you investigate potentially generating the client and types from the spec you made Or is that the case here

petermcd · Answer

In the event it is useful for anyone I created a very basic python package for getting data from the api also has the ability to see if a new version exists https github com petermcd turing pi bmc

phearzero · Answer

Yea that is going to be a long term plan The current routes do not generate very well going to spend some time on it this weekend It worked fine for the react project I started with but it was not pretty

phearzero · Answer

We should add a peers endpoint to the bmc api that returns a multicast dns request to the currently configured network It will return a list of other BMC s that the current node discovered As per discussion https discord com channels 754950670175436841 1080282784570019942 1099533702603735091

_dhanos_ · Answer

I will still suggest to have some time to think of it instead of making decisions this way I don t yet fully know which approach will be the best

_dhanos_ · Answer

What I mean partially is I m still not sure if the backends should communicate or the fronts should simultaneously query multiple backends If the backends communicate that d mean timeouts when at least one is unreachable and the whole interface will be unresponsive If the fronts handle this they can just show right statuses There also might be nore ways to solve this This is why this might not necessarily be a way I would not make someone work on something that might not be used Things should be better thought than a brief talk

phearzero · Answer

Agreed this is a RFC spec no implementation Just definitions

phearzero · Answer

Here is a scaffolding for a V2 API https github com PhearZero zero pi 2 blob issue 5 Feature V2 REST API app bmc webserver c L714