<div dir="ltr">Hi OpenStack docs aficionados - I wanted to make sure you all know the latest with the API "specs" migrations. Here's what I sent to 20+ PTLs today.<div><br></div><div>-----<br><div><br></div><div>

<div style="font-family:arial,sans-serif;font-size:12.727272033691406px">Hi all y'all PTLs:</div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px"><br></div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px">

tl;dr: Please approve my upcoming patch to your <project>-specs repo to get the API "spec" into your repo. Voice concerns here and now.</div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<br></div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px">Many of the API reference documents were meant for the contributor developer to know what was going into an API. So, the history of that document was forged as a specification. As projects beyond swift and nova were added, projects made similar documents. They're output to HTML at <a href="http://docs.openstack.org/api/api-specs.html" target="_blank">http://docs.openstack.org/api/api-specs.html</a>. However, as we now have a <project>-specs repo, it makes sense to move to those repos. In that move, also it makes sense to migrate to RST rather than DocBook/WADL. We'll continue with WADL to build the long API reference listing until a suitable replacement can be found. I'm hoping for the Swagger 2.0 specification to meet our needs, then I'll work on a migration plan for the reference information. This plan is scoped just for the "longer-form" API specification. I'll write a similar email to the openstack-dev list once you all clear the plan for takeoff. If you have concerns, let me know by Friday 8/22.</div>

<div style="font-family:arial,sans-serif;font-size:12.727272033691406px"><br></div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px">The Juno projects where this document needs to migrate to a specification are:</div>

<div style="font-family:arial,sans-serif;font-size:12.727272033691406px">nova (compute-api) v2, v3</div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px">swift (object-api) v1</div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px">

glance (image-api) v1, v1.1, v2</div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px">keystone (identity-api) v2.0, v3</div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px">

neutron (netconn-api) v1.0, v2.0</div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px">cinder (volume-api) v1.0, v2.0</div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px">
<br>
</div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px">Juno projects that have this type of document in a separate <service>-api repo are:</div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px">

trove (trove)</div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px"><br></div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px">Juno projects that do not provide this type of prose-based spec for their API are:</div>

<div style="font-family:arial,sans-serif;font-size:12.727272033691406px">ceilometer</div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px">heat</div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px">

sahara</div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px"><br></div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px">Incubating projects, this information is just a heads-up so you know how we're thinking about API documentation going forward.</div>

<div style="font-family:arial,sans-serif;font-size:12.727272033691406px">ironic</div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px">zaqar (marconi)</div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px">

barbican</div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px">designate</div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px"><br></div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px">

I'm going to do the migration work with pandoc and propose the patch to the project's repo. Be on the lookout for those patches. Please let me know if you see issues with this plan -- so far everyone has been very excited to welcome their RST documentation overlords for API prose.</div>

<div style="font-family:arial,sans-serif;font-size:12.727272033691406px"><br></div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px">Thanks,</div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px">

Anne</div></div></div></div>