https://turingpi.com logo
Join Discord
Powered by
OpenAPI and REST services.
# │forum
p
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:
Copy code
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
d
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 )
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.
p
Yea there is a lot that can be added. The root levels are usually good places to compose all of state. Request:
Copy code
bash
curl -X GET 127.0.0.1/api/bmc/node/1
Response:
Copy code
json
{
  info: "unkown",
  power: 1,
  usb: 0,
}
Patch:
Copy code
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
Copy code
json
{
  "usb": 0,
  "other": {},
  "node1": {  
    info: "unkown",
    power: 1,
    usb: 0,
  },
  "node2": {  
    info: "unkown",
    power: 1,
    usb: 0,
  }
}
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
d
Did you investigate potentially generating the client and types from the spec you made? Or is that the case here?
p
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
p
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 🤣 .
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
d
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
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.
p
Agreed, this is a RFC spec no implementation. Just definitions
2 Views
PreviousNext
Powered by