api documentation should be written from a user perspective

Bug #1596071 reported by David Britton on 2016-06-24
10
This bug affects 1 person
Affects Status Importance Assigned to Milestone
juju
Medium
Unassigned

Bug 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, 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!

description: updated
Changed in juju-core:
status: New → Triaged
importance: Undecided → Medium
tags: added: api docs usability
Curtis Hovey (sinzui) on 2016-08-23
affects: juju-core → juju
tags: added: helptext
To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Other bug subscribers