Define the REST API in some machine-readable formalism

NAICNO / Jobanalyzer

Easy to use resource usage report

MIT License

0 stars 1 forks source link

Define the REST API in some machine-readable formalism #502

Open lars-t-hansen opened 6 months ago

lars-t-hansen commented 6 months ago

One thing that came up in discussions at the AHM was that we need to define the REST API to naic-monitor in a way that allows it to be used by clients that don't want to go via sonalyze. This probably involves using some sort of standard API spec tech (something was mentioned but I forget which). cc @ashenr. We need to define both the query packets and the result packets, with explicit syntax & semantics for all the data fields. This is better defined and documented in the new Go version of the server than in the old Rust version, but it's still going to be a substantial job.

[x] Get rid of the xxxxxtruexxxxx hack, this means updating the server first to understand boolean parameters that don't have this special value, and then the clients can follow
[x] Write a spec for the current API
[ ] Attempt to define the current API in terms of standard tech like Swagger

lars-t-hansen commented 5 months ago

The tool we may want to use is Swagger, there is a Go implementation at https://github.com/swaggo/swag for example. Since our REST API is fairly narrow - there's basically one API for every command verb, and there are few verbs - we'll have to see if this is the most appropriate technology, but there's anyway a lot of inspiration to be had here.

lars-t-hansen commented 5 months ago

We can also get rid of the xxxxxtruexxxxx hack, this was an artifact of using the Rust command line parser.

lars-t-hansen commented 2 months ago

Note for example that the sacctd.sh script on Fox uses the xxxxtruexxxxx hack because the add command takes a boolean flag for the type of data (the alternative would have been -type=n which I think is probably better).

lars-t-hansen commented 2 months ago

At least now there's a definition document so that it's possible for other tools to create requests directly, plus some bug fixes and a spec of values that are scrubbed. Any machine-readable specification will have to wait.

lars-t-hansen commented 2 months ago

(Still need to deploy the new server before standard boolean values can be used in requests.)

lars-t-hansen commented 1 month ago

One weakness I'm perceiving in the current setup is that all the verbs are top-level elements of the path, ie https://naic-monitor.uio.no/load?..., which means the nginx config has to be updated every time we add a verb and there have to be special workarounds for normal file access. A better idea might be for all verbs to be underneath a top-level element eg https://naic-monitor.uio.no/op/load?.... Then we setup for the op/ element once and never look back.