[openstack-dev] [api] APIs schema consumption discussion
gdubreui at redhat.com
Thu Nov 16 01:56:48 UTC 2017
On 15/11/17 03:07, Doug Hellmann wrote:
> 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?
I'm glad you said that :).
Working directly from YAML or JSON files (format to be discussed) to
maintain the schema seems (to me too) the natural approach.
Meaning every project to change current practice: maintain the schema
files instead of maintaining RST files.
I suppose there has been suggestion to do it the other way (parse the
RST files) because of the latter impact on the current practice, but it
shouldn't be a blocker.
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
Senior Software Engineer, Openstack DFG Integration
Mobile: +61 400 894 219
Email: gilles at redhat.com
More information about the OpenStack-dev