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? Doug __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
