[openstack-dev] [api] APIs schema consumption discussion
doug at doughellmann.com
Tue Nov 14 16:07:49 UTC 2017
Excerpts from Gilles Dubreuil's message of 2017-11-14 10:15:02 +1100:
> Follow-up conversation from our last "API SIG feedback and discussion
> session" at Sydney Summit , 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 ( 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 . 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  and help the Misty project  (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
> APIs consumers and providers, any thoughts?
>  https://github.com/openstack/nova/tree/master/api-guide/source
>  https://developer.openstack.org/api-guide/quick-start/index.html
>  https://github.com/flystack/openstack-APIs
>  https://github.com/flystack/misty
Please do not build something that looks like SOAP based on parsing RST
files. Surely we can at least work directly from JSONSchema inputs?
More information about the OpenStack-dev