Open Stack

Excerpts from Gilles Dubreuil's message of 2017-11-14 10:15:02 +1100:
> Hi,
> 
> Follow-up conversation from our last "API SIG feedback and discussion 
> session" at Sydney Summit [1], about APIs schema consumption.
> 
> Let's summarize the current situation.
> 
> Each OpenStack project has an "API-source" folder containing RST files 
> describing its API structure ([2] for example). Those files are in turn 
> consumed by the Sphinx library to generate each project's API reference 
> manual which are then available in the API guide documentation [3]. Such 
> effort has made the APIs harmoniously consistent across all OpenStack 
> projects and has also created a "de-facto" API schema.
> 
> While the RST files are used by the documentation, they are not readily 
> consumable by SDKs. Of course the APIs schema can be extracted by web 
> crawling the Reference guides, which in turn can be used by any 
> language. Such approach works [4] and help the Misty project [5] (Ruby 
> SDK) started with more languages to exploit the same approach.
> 
> Therefore to allow better automation, the next step would be to have the 
> APIs schema stored directly into each project's repo so the SDKs could 
> consume them straight from the source. This is why we've started 
> discussing how to have the schema either extracted from the RST files or 
> alternatively having the API described directly into its own file. The 
> latter would provide a different work flow: "Yaml -> RST -> Reference 
> doco" instead of "RST -> Reference doco -> Yaml".
> 
> So the question at this stage is: "Which of the work flow to choose from?".
> 
> To clarify the needs, it's important to note that we found out that none 
> of the SDKs project, besides OSC (OpenStack Client, thanks to Dean), 
> have full time working teams to maintain each SDK, which besides the 
> natural structural complexity inherent to the cloud context, makes the 
> task of keeping a SDK up to date very difficult. Especially as projects 
> moves forward. Automatically managing Openstack APIs is inevitable for 
> consumers. Another example/feedback was provided by the presenters of 
> "AT&T’s Strategy for Implementing a Next Generation OpenStack Cloud" 
> session during Sydney Keynotes, as they don't handle the Openstack API 
> manually!
> 
> APIs consumers and providers, any thoughts?
> 
> [1] 
> https://www.openstack.org/summit/sydney-2017/summit-schedule/events/20442/api-sig-feedback-and-discussion-session
> [2] https://github.com/openstack/nova/tree/master/api-guide/source
> [3] https://developer.openstack.org/api-guide/quick-start/index.html
> [4] https://github.com/flystack/openstack-APIs
> [5] https://github.com/flystack/misty
> 
> Regards,
> Gilles

Please do not build something that looks like SOAP based on parsing RST
files. Surely we can at least work directly from JSONSchema inputs?

Doug