Open Stack

Hello,

In order to continue and progress on the API Schema guideline [1] as 
mentioned in [2] to make APIs more machine-discoverable and also 
discussed during [3].

Unfortunately until a new or either a second meeting time slot has been 
allocated,  inconveniently for everyone, have to be done by emails.


 > We felt that this was more of a one-off need rather than something 
we'd like to see rolled out across all OpenStack APIs.


Of course new features have to be decided (voted) by the community but 
how does that work when there are not enough people voting in?
It seems unfair to decide not to move forward and ignore the request 
because the others people interested are not participating at this level.

It's very important  to consider the fact "I" am representing more than 
just myself but an Openstack integration team, whose members are 
supporting me, and our work impacts others teams involved in their open 
source product consuming OpenStack. I'm sorry if I haven't made this 
more clear from the beginning, I guess I'm still learning on the 
particiaption process. So from now on, I'm going to use "us" instead.

Also from discussions with other developers from AT&T (OpenStack summit 
in Sydney) and SAP (Misty project) who are already using automation to 
consume APIs, this is really needed.

I've also mentioned the now known fact that no SDK has full time 
resources to maintain it (which was the initial trigger for us) more 
automation is the only sustainable way to continue the journey.

Finally how can we dare say no to more automation? Unless of course, 
only artisan work done by real hipster is allowed ;)


 > Furthermore, API-Schema will be problematic for services that use 
microversions. If you have some insight or opinions on this, please add 
your comments to that review.


I understand microversion standardization (OpenAPI) has not happened yet 
or if it ever does but that shouldn't preclude making progress.
As a matter of fact we can represent different versions of a resource in 
many ways just not in standardized fashion, and in the simplest (or 
worst case) scenario an API Schema can represent only one microversion 
version, more likely the latest at a specific point of time such Schema 
was built.


Also responding to [4]:

<cdent>  the goal, from gilles, is being able to create client code that works against real deployments


In some initial brainstorm discussion effectively came up the idea of 
doing of building the SDK client dynamically against any OpenStack 
service. For instance, depending on the specific (micro)versions 
supported by the servers the API schema would be given in response. 
Although an interesting idea, we are not talking about such feature, 
which could be an interesting academic topic (or not!).

So summarize and clarify, we are talking about SDK being able to build 
their interface to Openstack APIs in an automated way but statically 
from API Schema generated by every project. Such API Schema is already 
built in memory during API reference documentation generation and could 
be saved in JSON format (for instance) (see [5]).

[1] https://review.openstack.org/#/c/524467/
[2] 
http://lists.openstack.org/pipermail/openstack-dev/2018-February/127140.html
[3] 
eavesdrop.openstack.org/meetings/api_sig/2018/api_sig.2018-02-08-16.00.log.html#l-95
[4] 
http://eavesdrop.openstack.org/meetings/api_sig/2018/api_sig.2018-02-08-16.00.log.html#l-127
[5] https://review.openstack.org/#/c/528801

Cheers,
Gilles

On 16/03/18 04:30, Chris Dent wrote:
>
> Greetings OpenStack community,
>
> A rousing good time at the API-SIG meeting today. We opened with some 
> discussion on what might be missing from the Methods [7] section of 
> the HTTP guidelines. At the PTG we had discussed that perhaps we 
> needed more info on which methods were appropriate when. It turns that 
> what we probably need is better discoverability, so we're going to 
> work on that but at the same time do a general review of that entire 
> page.
>
> We then talked about microversions a bit (because it wouldn't be an 
> API-SIG without them). There's an in-progress history of microversions 
> document (linked below) that we need to decide if we'll revive. If you 
> have a strong opinion, let us know.
>
> And finally we explored the options for how or if Neutron can cleanly 
> resolve the handling of invalid query parameters. This was raised a 
> while back in an email thread [8]. It's generally a good idea not to 
> break existing client code, but what if that client code is itself 
> broken? The next step will be to make the choice configurable. Neutron 
> doesn't support microversions so "throw another microversion at it" 
> won't work.
>
> As always if you're interested in helping out, in addition to coming 
> to the meetings, there's also:
>
> * The list of bugs [5] indicates several missing or incomplete 
> guidelines.
> * The existing guidelines [2] always need refreshing to account for 
> changes over time. If you find something that's not quite right, 
> submit a patch [6] to fix it.
> * Have you done something for which you think guidance would have made 
> things easier but couldn't find any? Submit a patch and help others [6].
>
> # Newly Published Guidelines
>
> None this week.
>
> # API Guidelines Proposed for Freeze
>
> Guidelines that are ready for wider review by the whole community.
>
> None this week.
>
> # Guidelines Currently Under Review [3]
>
> * Add guidance on needing cache-control headers
>   https://review.openstack.org/550468
>
> * Add guideline on exposing microversions in SDKs
>   https://review.openstack.org/#/c/532814/
>
> * Add API-schema guide (still being defined)
>   https://review.openstack.org/#/c/524467/
>
> * A (shrinking) suite of several documents about doing version and 
> service discovery
>   Start at https://review.openstack.org/#/c/459405/
>
> * WIP: microversion architecture archival doc (very early; not yet 
> ready for review)
>   https://review.openstack.org/444892
>
> # Highlighting your API impacting issues
>
> If you seek further review and insight from the API SIG about APIs 
> that you are developing or changing, please address your concerns in 
> an email to the OpenStack developer mailing list[1] with the tag 
> "[api]" in the subject. In your email, you should include any relevant 
> reviews, links, and comments to help guide the discussion of the 
> specific challenge you are facing.
>
> To learn more about the API SIG mission and the work we do, see our 
> wiki page [4] and guidelines [2].
>
> Thanks for reading and see you next week!
>
> # References
>
> [1] http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> [2] http://specs.openstack.org/openstack/api-wg/
> [3] 
> https://review.openstack.org/#/q/status:open+project:openstack/api-wg,n,z
> [4] https://wiki.openstack.org/wiki/API_SIG
> [5] https://bugs.launchpad.net/openstack-api-wg
> [6] https://git.openstack.org/cgit/openstack/api-wg
> [7] 
> http://specs.openstack.org/openstack/api-wg/guidelines/http.html#http-methods
> [8] 
> http://lists.openstack.org/pipermail/openstack-dev/2018-March/128023.html
>
> Meeting Agenda
> https://wiki.openstack.org/wiki/Meetings/API-SIG#Agenda
> Past Meeting Records
> http://eavesdrop.openstack.org/meetings/api_sig/
> Open Bugs
> https://bugs.launchpad.net/openstack-api-wg
>
>
>
> __________________________________________________________________________
> 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


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20180316/11ed0bd2/attachment.html>