Open Stack

On Tue, May 16, 2017 at 4:13 PM, Monty Taylor <mordred at inaugust.com> wrote:

> Hey all!
>
> I read the API docs A LOT. (thank you to all of you who have worked on
> writing them)
>
> As I do, a gotcha I hit up against a non-zero amount is mapping the
> descriptions of the response parameters to the form of the response itself.
> Most of the time there is a top level parameter under which either an
> object or a list resides, but the description lists list the top level and
> the sub-parameters as siblings.
>
> So I wrote a patch to os-api-ref taking a stab at providing a way to show
> things a little differently:
>
> https://review.openstack.org/#/c/464255/
>
> You can see the output here:
>
> http://docs-draft.openstack.org/55/464255/5/check/gate-nova-
> api-ref-src/f02b170//api-ref/build/html/
>
> If you go expand either the GET / or the GET /servers/details sections and
> go to look at their Response sections, you can see it in action.
>
> We'd like some feedback on impact from humans who read the API docs
> decently regularly...
>
> The questions:
>
> - Does this help, hurt, no difference?
>

It helps. It seems noisy at first glance, but the information being denoted
is important. It's one of those situations where once you start reading
deeper into the information, this kind of markup makes the API more
understandable more quickly.


> - servers[].name - servers is a list, containing objects with a name
> field. Good or bad?
> - servers[].addresses.$network-name - addresses is an object and the keys
> of the object are the name of the network in question.
>

Again, these seem noisy at first, but having parsed complex paths,
especially the above address info, by dumping variables too many times, I
really appreciate the above syntax.

Going even further:

servers[].addresses.$network-name[].OS-EXT-IPS-MAC:mac_addr

looks a mess, but I can see how exactly to navigate to the leaf as well as
understand what types make up the path. Being able to succinctly
(relatively/subjectively speaking) describe something like the above is
very helpful. This definitely gets my support.

Thanks,
Joe
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20170517/b7155ef4/attachment.html>