Open Stack

On 15/11/17 03:07, Doug Hellmann wrote:
> 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?

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.

Gil

>
> Doug
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

-- 
Gilles Dubreuil
Senior Software Engineer, Openstack DFG Integration
Mobile: +61 400 894 219
Email: gilles at redhat.com
GitHub/IRC: gildub