<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
</head>
<body text="#000000" bgcolor="#FFFFFF">
<p>Hi,</p>
<p>Follow-up conversation from our last "API SIG feedback and
discussion session" at Sydney Summit [1], about APIs schema
consumption.</p>
<p>Let's summarize the current situation. <br>
</p>
<p>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. <br>
</p>
<p>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. <br>
</p>
<p>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". <br>
</p>
<p>So the question at this stage is: "Which of the work flow to
choose from?".<br>
</p>
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 "<span class="event-title">AT&T’s
Strategy for Implementing a Next Generation OpenStack Cloud</span>"
session during Sydney Keynotes, as they don't handle the Openstack
API manually!<br>
<br>
APIs consumers and providers, any thoughts?<br>
<br>
[1] <a class="moz-txt-link-freetext"
href="https://www.openstack.org/summit/sydney-2017/summit-schedule/events/20442/api-sig-feedback-and-discussion-session">https://www.openstack.org/summit/sydney-2017/summit-schedule/events/20442/api-sig-feedback-and-discussion-session</a><br>
[2] <a class="moz-txt-link-freetext" href="https://github.com/openstack/nova/tree/master/api-guide/source">https://github.com/openstack/nova/tree/master/api-guide/source</a><br>
[3] <a class="moz-txt-link-freetext" href="https://developer.openstack.org/api-guide/quick-start/index.html">https://developer.openstack.org/api-guide/quick-start/index.html</a><br>
[4] <a class="moz-txt-link-freetext" href="https://github.com/flystack/openstack-APIs">https://github.com/flystack/openstack-APIs</a><br>
[5] <a class="moz-txt-link-freetext" href="https://github.com/flystack/misty">https://github.com/flystack/misty</a><br>
<p>Regards,<br>
Gilles<br>
</p>
</body>
</html>