On Wed, 2019-01-09 at 08:39 +0100, Ulrich Windl wrote: > > > > Ken Gaillot <[email protected]> schrieb am 08.01.2019 um > > > > 18:28 in > > Nachricht > <[email protected]>: > > On Tue, 2019-01-08 at 17:23 +0100, Kristoffer Grönlund wrote: > > > On Tue, 2019-01-08 at 10:07 -0600, Ken Gaillot wrote: > > > > On Tue, 2019-01-08 at 10:30 +0100, Kristoffer Grönlund wrote: > > > > > On Mon, 2019-01-07 at 17:52 -0600, Ken Gaillot wrote: > > > > > > > > > > > > > > > > Having all the tools able to produce XML output like cibadmin > > > > > and > > > > > crm_mon would be good in general, I think. So that seems like > > > > > a > > > > > good > > > > > proposal to me. > > > > > > > > > > In the case of an error, at least in my experience just > > > > > getting a > > > > > return code and stderr output is enough to make sense of it - > > > > > getting > > > > > XML on stderr in the case of an error wouldn't seem like > > > > > something > > > > > that > > > > > would add much value to me. > > > > > > > > There are two benefits: it can give extended information (such > > > > as > > > > the > > > > text string that corresponds to a numeric exit status), and > > > > because > > > > it > > > > would also be used by any future REST API (which won't have > > > > stderr), > > > > API/CLI output could be parsed identically. > > > > > > > > > > Hm, am I understanding you correctly: > > > > > > My sort-of vision for implementing a REST API has been to move > > > all of > > > the core functionality out of the command line tools and into the > > > C > > > libraries (I think we discussed something like a > > > libpacemakerclient > > > before) - the idea is that the XML output would be generated on > > > that > > > level? > > > > > > If so, that is something that I am all for :) > > > > Yes :) but this would not be an implementation, just an output > > format > > that a future implementation could use. > > > > The idea for the future is that a C library would contain all the > > functionality, and the CLI tools and REST API daemon would just be > > thin > > wrappers for that. Both the CLI (with XML output option) and REST > > API > > would return identical output, so scripts/tools could be written > > that > > could easily use one or the other. > > If the REST API should implement a reliable interface, the output > (actually > the data being returned) must be formalized ("machine readable"). One > part > could be a clear-text message intended for humans, but there must be > more than > that.
Exactly, formalizing it is what I would like to do now. The CLI tools would be able to generate output in a selectable format, defaulting to human-friendly plain text, but optionally something machine-readable like XML instead. crm_mon already does this; it offers options for plain-text, curses, HTML, CGI, nagios, or XML output. My plan is that CLI tool XML output (to begin being implemented now) would be identical to (theoretical future) REST API XML output. Scripts/tools could be written now to parse CLI XML output, and if we ever proceed with a REST API, all of that code will be reusable as-is. > (Recently I learned some commercial REST API interface that seemed to > be > "knitted with a hot needle": It is highly inconsistent on parameter > names, on > parameter passing methods, on parameter and response formats. Also > the methods > used (GET/POST/DELETE) are used inconsitently. I mean this is exactly > what we > DO NOT want). Definitely, that's why I'm raising the visibility on this :) But at the moment we are solely concerned with the result format, not the API itself. > > But at this point, we're just talking about the output format, and > > implementing it for a few CLI commands as a demonstration. The > > first > > step in the journey. > > One point not discussed so far (but important): How would > authentication > between CLI tools and the REST API work? With authentication, none of > the > user-side tools would have to run as root. Yes, that is an open question, but we're nowhere near that stage yet, just defining the result format. To be clear, a REST API is not a priority and there are no plans to implement one. But there are plans to implement machine-readable CLI output, and I'd like to make sure it can be reused identically for any future API. > > > Right now, we are experimenting with a REST API based on taking > > > what > > > we > > > use in Hawk and moving that into an API server written in Go, and > > > just > > > calling crm_mon --as-xml to get status information that can be > > > exposed > > > via the API. Having that available in C directly and not having > > > to > > > call > > > out to command line tools would be great and a lot cleaner: > > Before going that way, I would revalidate the API with some of the > criteria > mentioned above. A consistent, reliable and secure API is very much > desired. > > > > > > > https://github.com/krig/hawk-apiserver > > > https://github.com/hawk-ui/hawk-web-client > > > > > > Cheers, > > > Kristoffer > > > > So it looks like you're using JSON for the results returned by an > > API > > query? That's part of the question here. I think we're more likely > > to > > go with XML, but you're already parsing XML from crm_mon, so that > > shouldn't pose any problems if you want to parse and reformat the > > CLI > > output. > > Actually a long as XML is used just to represent nested data (without > a clean > DTD), JSON is preferrable, because it's easier to parse. Maybe the > client could > specify in the accept header with format it wants to receive... > > > > > I envision a future pacemaker API server offering multiple output > > formats based on request extension, e.g. /GET/resources/my-rsc- > > id.xml > > would return XML whereas my-rsc-id.json would return JSON, > > optionally > > with an additional .bz2 extension to compress the result. But > > that's > > all just dreaming at this point, and there are no concrete plans to > > implement it. > > No: HTTP has a standard mechanism for the returned data type; don't > add > multiple URIs to specify the data type to return. That'll be the > start of a > mess otherwise. Oh right, I don't know why I forgot that. > > The questions at this point are: > > > > 1. What output format(s) should we offer? (likely just XML for now, > > with a design allowing for alternatives just as JSON in the future) > > > > 2. What should the command-line interface be? (e.g. --output-as=xml > > -- > > output-file=result.xml) > > Command-line interface for what? The output of the command-line tools > should > be plain text unless you provide a generic REST API wrapper to use > any REST > function. The API is vaporware :) while the CLI is real, so we're starting with that. The question is what command-line options should be used to select the output format (defaulting to plain text). > > 3. What should the output schema look like? For example, how should > > we > > represent the output of "stonith_admin --history" and "crm_resource > > -- > > list-operations"? The goal will be to have something general enough > > that it can be easily adapted to any command, yet consistent enough > > to > > be easily parsed. > > Please don't make a generic "one size fits all XML"; instead make > specific > DTDs for the individual result types. As a counter-example, the most > useless > XML format would be: > <output>...any output...</output> > > On theother hand, wrapping X structs in XML is just as bad. > > Summary: making a clean design is worth it! Yes, that's the question! :) -- Ken Gaillot <[email protected]> _______________________________________________ Users mailing list: [email protected] https://lists.clusterlabs.org/mailman/listinfo/users Project Home: http://www.clusterlabs.org Getting started: http://www.clusterlabs.org/doc/Cluster_from_Scratch.pdf Bugs: http://bugs.clusterlabs.org
