Open Stack

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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20171114/0dba0d49/attachment.html>