<div dir="ltr">Hi all, <div>I wanted to be sure to post to the dev, docs, and user mailing lists about the progress towards supporting application devs using OpenStack REST APIs. We discussed at the cross-project meeting today and you can read more details in the meeting log. [1]</div><div><br></div><div>This blog post [2] explains what's happening this month with a migration as well as build jobs that enable project teams to write tutorials and how-to guides. <div><br></div><div>This Thursday afternoon/ early Friday morning, the new fairy-slipper core team [3] is meeting in Google Hangout to get to put faces to names. Feel free to join us if you're interested!</div><div><br></div><div>I'll be reaching out to the API working group liaisons [4] to be sure you all are up-to-date and can take any next actions you need to. You're always welcome to attend the doc team meeting which has a standing item about API doc and design.</div><div><br></div><div>Thanks to everyone who got us this far -- Russell Sim and Karen Bradshaw especially! Also, thanks to the API working group and the nova API specialty team for poking at the early work and being willing to carry the torch. And of course, Diane Fleming's work accounts for over 60% of all patches for the <a href="http://developer.openstack.org">http://developer.openstack.org</a> site, her volume and quality of work is wonderful. Thanks to Tom Fifield for connecting the dots and the peeps.</div><div><br></div><div>I also want to emphasize that over 120 individual contributors kept the API reference info updated in the last release, and that long tail of contributions is what's keeping this valuable info accurate and trusted. Thanks to every one of you.</div><div>Anne</div><div><br></div><div>1. <a href="http://eavesdrop.openstack.org/meetings/crossproject/2016/crossproject.2016-01-12-21.02.log.html">http://eavesdrop.openstack.org/meetings/crossproject/2016/crossproject.2016-01-12-21.02.log.html</a></div><div>2. <a href="http://www.openstack.org/blog/2016/01/whats-next-for-application-developer-guides/">http://www.openstack.org/blog/2016/01/whats-next-for-application-developer-guides/</a>. <br></div><div>3. <a href="https://review.openstack.org/#/admin/groups/1240,members">https://review.openstack.org/#/admin/groups/1240,members</a></div><div>4. <a href="http://specs.openstack.org/openstack/api-wg/liaisons.html">http://specs.openstack.org/openstack/api-wg/liaisons.html</a></div><div><br></div><div>The full blog post is pasted below, for those who don't like to clickety-click-click too much. :)</div>What's new for application developer guides?<br>Summary<br>This month, the <a href="http://developer.openstack.org">developer.openstack.org</a> site gets a new look and changes its source tooling. Read on for details about how these changes affect your project team.<br><br>Why are we changing the <a href="http://developer.openstack.org">developer.openstack.org</a> site?<br>You might know that the <a href="http://developer.openstack.org">developer.openstack.org</a> site documents over 900GET/PUT/POST/DELETE/PATCH calls for a dozen OpenStack services already on the <a href="http://developer.openstack.org">developer.openstack.org</a> site. As a couple of the keynote speakers in Tokyo so elegantly put it, the trustworthiness and consistency of the OpenStack APIs influenced their decision to run their business workloads in an OpenStack cloud.<br><br>Those interfaces need docs, lots of docs, and not only reference docs. While it takes a huge effort to maintain accurate references, we also need to document API usage and scenarios.<br><br>Now that we’ve written both an API Guide and a “Writing your first OpenStack application” tutorial, we want the site to be the go-to location for app devs, product developers, and anyone who needs to unlock the power of their OpenStack infrastructure.<br><br>In this release, the docs’ platform introduces tooling that lets you migrate from WADL to Swagger and integrate RST-sourced documentation with the API reference documentation. The “why” analysis is clear: we must community-source this info and make it easy to maintain and update so that users can trust it enough to bet their workloads on it.<br><br>Later on, this post answers the “how” questions.<br><br>Why all these changes at this point in the release?<br>Well, we haven’t had to release the API documentation like we release services documentation. We have done a lot of maintenance on the site, with bug fixing and so on. But it’s time to take the leap. Last release we made a proof-of-concept. This release we unleash a solution that helps us make incremental progress toward our goals.<br><br>How do you keep your API docs updated after January 16th?<br>On January 16th, we’ll migrate the Images API WADL and DocBook files to Swagger and RST files. Then we’ll test the build process and the content itself to validate the migration.<br><br>After testing, we will migrate the files for these services:<br><br>Identity<br>Compute<br>Images<br>Networks<br>Block Storage<br>Object Storage<br><br>Then, the remaining services can migrate their files by using the validated tooling.<br><br>If you do provide an OpenStack API service, read on.<br><br>For the nova project, place your how-to and conceptual articles in the api-guide folder in the nova repository. Other projects can mimic these patches that created an api-guide and build jobs for the Compute api-guide. You continue to update reference information in the openstack/api-site repo. However, the source files have changed.<br><br>With this release, you can embed annotations in your source code if you want to generate the reference information. Here’s an example patch from the nova project. Because we haven’t had a project do this yet completely, the build jobs still need to be written.<br><br>If your project already has WADL files, they will be migrated to Swagger files and stored in the api-site repository. The WADL files will be deleted; you can retrieve them from Git.<br><br>If your project does not have a WADL file, then you write Swagger plus RST to document your API calls, parameters, and reference information. You can generate Swagger from annotations or create Swagger from scratch that you store in the api-site repository. You should review, store, and build RST for conceptual or how-to information from within your project team’s repository.<br><br>All projects should use this set of API documentation guidelines from the OpenStack API working group any time their service has a REST API. This document tells you what and how much to write. If you follow the suggested outline, your API guide will be accurate and complete.<br><br>After the source files and build jobs exist, the docs are built to <a href="http://developer.openstack.org">developer.openstack.org</a>.<br><br>Where can I get help for my project’s API Guides?<br><br>These specifications describe the details: Application Developer Guides and Rework API Reference Information.<br><br>You can ask questions in #openstack-sdks or #openstack-docs on IRC. We await those magical API docs fairies who grant wishes, but in the meantime but we can point you in the right direction and give you the tools for your quest.<br><br>What if I still have questions?<br><br>Contact me, Anne Gentle, by email or IRC and I’ll get back to you as soon as possible.<br><br>I’m eager to enable our audience with great user-centric docs and hope that you’ll join us as we fulfill the vision.-- <br><div class="gmail_signature"><div dir="ltr"><div>Anne Gentle</div><div>Rackspace</div><div>Principal Engineer</div><div><a href="http://www.justwriteclick.com" target="_blank">www.justwriteclick.com</a></div></div></div>
</div></div>