I think it makes sense to have an openstack-api project with all the API docs (specs and learning materials) gathered in one place. I think it's preferable to have the API separated out from the code for several reasons - ease of review, ease of check out, also for learning materials for the API itself.<br>
<br>I'd envision these would go in it for starters:<br><br>Compute API (docbook, core + extensions)<br>Glance API (RST to docbook, core)<br>Keystone API (docbook, incubation, core + extensions)<br>Swift API (docbook, core)<br>
<br>Notes: <br>- Yep, Keystone moved their docbook out of the core code base due to the "overhead" associated with a large-ish document ensconced with the code. <br>- Glance's API is documented in a single RST page. We have a simple RST to docbook tool inhouse at Rackspace that lets me take updates and move them into docbook.<br>
- Just today I had a request to bring the Load Balancing API into
openstack-manuals for comments and review from
<a href="http://wiki.openstack.org/Atlas-LB">http://wiki.openstack.org/Atlas-LB</a>, since our wiki doesn't enable comments. I'm not sure what to do with nascent APIs for review that aren't yet in incubation. <br>
<br>So these are some of my observations having worked with the API docs for a while, to consider while seeking the ideal solution: <br>Incubation - how do we indicate an API is incubated? <br>Pre-incubation/review period - how could a team offer an API up for community review and commenting?<br>
Core - how do we indicate what is core and how to get extensions? At Rackspace the Compute API team is working on a solution to getting extensions and telling people how to use them once they're available. <br>Source - DocBook is the source for the two biggest API docs, Compute and Object Storage, Keystone is a close third, and I can get DocBook out of Glance. Do we need to set DocBook as the standard source? <br>
Output - I'd also like to focus on not only API specs but also deliverables that help people learn the APIs, such as the frameworks recently opensourced by Mashery (example: <a href="http://developer.klout.com/iodocs" target="_blank">http://developer.klout.com/iodocs</a>) and Wordnik (<a href="http://swagger.wordnik.com/" target="_blank">http://swagger.wordnik.com/</a>). If we also deliver this type of web tool, we'd also need JSON or XML as source files (many of which are already embedded into the DocBook).<br>
<br>I'd like the best of both worlds - API specs and self-documenting APIs. I think we can get there, and I think a separate API project with a core review team moves us in that direction.<br><br>Thanks for the good discussion here. <br>
Anne<br><br><div id="WISESTAMP_SIG_9103"><div style="font-size: 13.3px; font-family: Verdana,Arial,Helvetica,sans-serif;"><div style="margin: 0pt 0pt 8px;"><p style="margin: 0pt;"><span style="font-size: x-small;"><span style="font-size: xx-small;"><strong><span style="font-size: 8pt;"><span> </span></span></strong></span></span></p>
<div style="padding: 5px; font-size: 11px; color: rgb(102, 102, 102); font-family: sans-serif;"><strong>Anne Gentle</strong> <br><a href="http://www.facebook.com/conversationandcommunity"></a>
<div style="font-size: 10px;"><a href="http://justwriteclick.com/" target="_blank">my blog</a> | <a href="http://xmlpress.net/publications/conversation-community/" target="_blank">my book</a> | <a href="http://www.linkedin.com/in/annegentle" target="_blank"><span class="il">LinkedIn</span></a> | <a href="http://del.icio.us/annegentle" target="_blank">Delicious</a> | <a href="http://twitter.com/annegentle" target="_blank">Twitter</a></div>
</div><div style="clear: both;"></div></div><img src="http://p1.wisestamp.com/pixel.png?p=mozilla&v=2.6.1.0&t=1314064151214&u=cb1a314a0c4ca423" height="1" width="1"></div></div><div class="gmail_quote">On Mon, Aug 22, 2011 at 7:49 PM, Jan Drake <span dir="ltr"><<a href="mailto:jan_drake@hotmail.com">jan_drake@hotmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">+1<br>
<div><div></div><div class="h5"><br>
<br>
<br>
<br>
On Aug 22, 2011, at 5:06 PM, Jay Pipes <<a href="mailto:jaypipes@gmail.com">jaypipes@gmail.com</a>> wrote:<br>
<br>
> ++<br>
><br>
> On Mon, Aug 22, 2011 at 7:59 PM, Jorge Williams<br>
> <<a href="mailto:jorge.williams@rackspace.com">jorge.williams@rackspace.com</a>> wrote:<br>
>> Hi Vish,<br>
>> I don't have a problem moving the spec out of docs manuals and into another<br>
>> project even the nova repo. But, I do have a number of issues with the<br>
>> approach that you're proposing. First, I think that fundamentally there<br>
>> should be a decoupling of the spec and the implementation. If you have the<br>
>> spec generated from the code than essentially the spec is whatever the code<br>
>> does. It's very difficult to interoperate with specs that are generated this<br>
>> way as the specs tend to be very brittle and opaque (since you have to study<br>
>> the code). If you introduce a bug in the code that bug filters it's way all<br>
>> the way to the spec (this was a big problem with SOAP and CORBA). It's<br>
>> difficult to detect errors because you cant validate. By keeping the<br>
>> implementation and the spec separate you can validate one against the other.<br>
>><br>
>> Second, I don't think that the core OpenStack API should change with every<br>
>> OpenStack release. There are a number of efforts to provide multiple<br>
>> implementation of an existing OpenStack API. We should encourage this, but<br>
>> it becomes difficult if the core spec is in constant flux. Certainly you<br>
>> can use the extension mechanism to bring functionality out to market<br>
>> quickly, but the process of deciding what goes into the core should be more<br>
>> deliberate. Really good specs, shouldn't need to change very often, think<br>
>> HTTP, X11, SMTP, etc. We need to encourage clients to write support for our<br>
>> spec and we need to also encourage other implementors to write<br>
>> implementations for it. These efforts become very difficult if the spec is<br>
>> in constant flux.<br>
>> -jOrGe W.<br>
>> On Aug 22, 2011, at 5:43 PM, Vishvananda Ishaya wrote:<br>
>><br>
>> Hey Everyone,<br>
>> We discussed at the Diablo design summit having API spec changes be proposed<br>
>> along with code changes and reviewed according to the merge process that we<br>
>> use for code. This has been impossible up until now because the canonical<br>
>> spec has been in the openstack-manuals project.<br>
>> My suggestion is that we move the openstack-compute spec into the nova<br>
>> source tree. During a six-month release we can propose changes to the spec<br>
>> by proposing along with the code that changes it. In the final freeze for<br>
>> the release, we can increment the spec version number and copy the current<br>
>> version of the spec into openstack-manuals and that will be the locked down<br>
>> spec for that release.<br>
>> This means that openstack 1.1 will be the official spec for diablo, at which<br>
>> point we will start working on a new api (we can call it 1.2 but it might be<br>
>> best to use a temporary name like 'latest') during the essex release cycle,<br>
>> then at essex release we lock the spec down and it becomes the new version<br>
>> of the openstack api.<br>
>> Ultimately I would like the spec to be generated from the code, but as a<br>
>> first pass, we should at least be able to edit the future version of the<br>
>> spec as we make changes. I've proposed the current version of the spec<br>
>> here:<br>
>> <a href="https://code.launchpad.net/%7Evishvananda/nova/add-api-docs/+merge/72506" target="_blank">https://code.launchpad.net/~vishvananda/nova/add-api-docs/+merge/72506</a><br>
>> Are there any issues with this approach?<br>
>> Vish<br>
>><br>
>> This email may include confidential information. If you received it in<br>
>> error, please delete it.<br>
>> _______________________________________________<br>
>> Mailing list: <a href="https://launchpad.net/%7Eopenstack" target="_blank">https://launchpad.net/~openstack</a><br>
>> Post to : <a href="mailto:openstack@lists.launchpad.net">openstack@lists.launchpad.net</a><br>
>> Unsubscribe : <a href="https://launchpad.net/%7Eopenstack" target="_blank">https://launchpad.net/~openstack</a><br>
>> More help : <a href="https://help.launchpad.net/ListHelp" target="_blank">https://help.launchpad.net/ListHelp</a><br>
>><br>
>><br>
><br>
> _______________________________________________<br>
> Mailing list: <a href="https://launchpad.net/%7Eopenstack" target="_blank">https://launchpad.net/~openstack</a><br>
> Post to : <a href="mailto:openstack@lists.launchpad.net">openstack@lists.launchpad.net</a><br>
> Unsubscribe : <a href="https://launchpad.net/%7Eopenstack" target="_blank">https://launchpad.net/~openstack</a><br>
> More help : <a href="https://help.launchpad.net/ListHelp" target="_blank">https://help.launchpad.net/ListHelp</a><br>
<br>
_______________________________________________<br>
Mailing list: <a href="https://launchpad.net/%7Eopenstack" target="_blank">https://launchpad.net/~openstack</a><br>
Post to : <a href="mailto:openstack@lists.launchpad.net">openstack@lists.launchpad.net</a><br>
Unsubscribe : <a href="https://launchpad.net/%7Eopenstack" target="_blank">https://launchpad.net/~openstack</a><br>
More help : <a href="https://help.launchpad.net/ListHelp" target="_blank">https://help.launchpad.net/ListHelp</a><br>
</div></div></blockquote></div><br>