| 2016-06-24 19:26:03 |
David Britton |
description |
What I have right now is this:
https://godoc.org/github.com/juju/juju/apiserver/
Which at least documents what is there technically and is quite complete, however it doesn't say how websockets should be used, what responses the api gives, what the methods actually do (typically one sentence that repeats the method name is all that is there), no examples of usage in a programming language (javascript, for instance) are given, etc.
Take this one example:
https://godoc.org/github.com/juju/juju/apiserver/action#ActionAPI.RunOnAllMachines
This method was actually changed in juju2 to be asynchronous, the return is very similar to what was in juju1, but the actions were just... not finished (would be great to note that in the docs). Leaving that aside though, the doc merely says:
"RunOnAllMachines attempts to run the specified command on all the machines."
Which is not enough to understand what is returned, how I can use it, what inputs are available (those are hidden behind links that are equally terse) what the call structure would like like over the api, not to mention that it's async and data needs to be polled to get results.
I'm humbly requesting that we take some time to expand the API docs and write them from a user perspective calling the api through websockets. Thanks! |
What I have right now is this:
https://godoc.org/github.com/juju/juju/apiserver/
Which at least documents what is there technically and is quite complete, however it doesn't say how websockets should be used, what responses the api gives, what the methods actually do (typically one sentence that repeats the method name is all that is there), no examples of usage in a programming language (javascript, for instance) are given, etc.
Take this one example:
https://godoc.org/github.com/juju/juju/apiserver/action#ActionAPI.RunOnAllMachines
This method was actually changed in juju2 to be asynchronous, the return is very similar to what was in juju1, but the actions were just... not finished, the doc merely says:
"RunOnAllMachines attempts to run the specified command on all the machines."
Which is not enough to understand what is returned, how I can use it, what inputs are available (those are hidden behind links that are equally terse) what the call structure would be like, and of course that it's async and data needs to be polled to get results (and how to actually do that).
I'm humbly requesting that we take some time to expand the API docs and write them from a user perspective calling the api through websockets. Thanks! |
|
