<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Tue, May 16, 2017 at 4:13 PM, Monty Taylor <span dir="ltr"><<a href="mailto:mordred@inaugust.com" target="_blank">mordred@inaugust.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex">Hey all!<br>
<br>
I read the API docs A LOT. (thank you to all of you who have worked on writing them)<br>
<br>
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.<br>
<br>
So I wrote a patch to os-api-ref taking a stab at providing a way to show things a little differently:<br>
<br>
<a href="https://review.openstack.org/#/c/464255/" rel="noreferrer" target="_blank">https://review.openstack.org/#<wbr>/c/464255/</a><br>
<br>
You can see the output here:<br>
<br>
<a href="http://docs-draft.openstack.org/55/464255/5/check/gate-nova-api-ref-src/f02b170//api-ref/build/html/" rel="noreferrer" target="_blank">http://docs-draft.openstack.or<wbr>g/55/464255/5/check/gate-nova-<wbr>api-ref-src/f02b170//api-ref/<wbr>build/html/</a><br>
<br>
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.<br>
<br>
We'd like some feedback on impact from humans who read the API docs decently regularly...<br>
<br>
The questions:<br>
<br>
- Does this help, hurt, no difference?<br></blockquote><div><br></div><div>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.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex">
- servers[].name - servers is a list, containing objects with a name field. Good or bad?<br>
- servers[].addresses.$network-n<wbr>ame - addresses is an object and the keys of the object are the name of the network in question.<br></blockquote><div><br></div><div>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.</div><div><br></div><div>Going even further:</div><div><br></div><div>servers[].addresses.$network-name[].OS-EXT-IPS-MAC:mac_addr<br></div><div><br></div><div>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.</div><div><br></div><div>Thanks,</div><div>Joe</div></div></div></div>