Open Stack

On 29/10/12 20:43, Anne Gentle wrote:
> On Fri, Oct 26, 2012 at 11:31 AM, Monty Taylor<mordred at inaugust.com>  wrote:
>> >On 10/26/2012 08:16 AM, Thierry Carrez wrote:
>>> >>The arguments of why we need an OpenStack Compute API rather than just
>>> >>adopting the AWS EC2 API can probably be made just the same for Heat...
>>> >>
>>> >>I expect this to become a critical point in the discussion.
>> >
>> >I do too. I do think however that our initial concerns over license/use
>> >of the API (I was one of the vocal advocates of not touching Amazon APIs
>> >for fear of a crazy Bezos running amok - you can go find my blog
>> >argument with Shuttleworth on the subject) have been mitigated by recent
>> >court cases that found APIs are not copyrightable (thanks for stupidly
>> >suing Google, Oracle!)
>> >
> I think there's a potential for slight worsening of the API docs
> situation ... but I'd like to hear statements pro and con introducing
> an API that we don't document into the OpenStack ecosystem. I really
> do want to understand this better and it's important that I do
> understand it from many perspectives, not just my "Anne from docland"
> view.

I'd just like to re-iterate that the CloudFormation compatible API is 
*NOT* the only API to Heat. There is an OpenStack-native API as well, 
and it will absolutely be documented.

I have updated the application page on the wiki to reflect this, so 
apologies to those who saw out-of-date information on there.

>
> About our API docs current state - there are about 30 bugs logged [1],
> some of the docs are specs, some are not, and API docs constantly need
> care and feeding, something we're not resourcing greatly. My
> understanding is there are about 25 API writers at Amazon, and in our
> open API world, no one is specifically tasked with documenting the
> OpenStack APIs (that I know of). Many of my conversations about docs
> are more with QA folks who want a spec to test against. Users of APIs,
> they seem to be managing, but I'm sure they'd also like more docs.
>
> So what I'd like to hear is not just that we need tests and
> development for API additions, but docs as well. What do you all
> envision as the doc plan for this type of API usage for OpenStack
> deployers?

The OpenStack-native API reference for Heat can be found here:
https://github.com/heat-api/heat/blob/master/docs/api.md#readme

It's currently at a pretty early stage because the code is at a pretty 
early stage, but the things that are not likely to change are 
documented. As we firm up things like the output format (this new API is 
a great chance to iron out some of the hideous AWS-isms) I expect to add 
them to the documentation until it is at least equivalent to the 
api.openstack.org site. At some point it probably should be translated 
into the same format as well.

regards,
Zane.

>
> Thanks for indulging my quest.
> Anne
>
> [1]https://bugs.launchpad.net/openstack-api-site
>