<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
<body text="#000000" bgcolor="#FFFFFF">
<p>Hello,</p>
<p>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].<br>
</p>
<p>Unfortunately until a new or either a second meeting time slot
has been allocated, inconveniently for everyone, have to be done
by emails.</p>
<p><br>
> 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. <br>
</p>
<p><br>
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?<br>
It seems unfair to decide not to move forward and ignore the
request because the others people interested are not participating
at this level.</p>
<p>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.<br>
<br>
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.</p>
<p>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. <br>
</p>
<p>Finally how can we dare say no to more automation? Unless of
course, only artisan work done by real hipster is allowed ;)<br>
</p>
<p><br>
> 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.<br>
</p>
<p><br>
I understand microversion standardization (OpenAPI) has not
happened yet or if it ever does but that shouldn't preclude making
progress.<br>
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.<br>
</p>
<br>
Also responding to [4]:<br>
<br>
<pre><span class="nk"><cdent></span> the goal, from gilles, is being able to create client code that works against real deployments</pre>
<br>
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!).<br>
<br>
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]). <br>
<br>
<p>[1] <a class="moz-txt-link-freetext" href="https://review.openstack.org/#/c/524467/">https://review.openstack.org/#/c/524467/</a><br>
[2]
<a class="moz-txt-link-freetext" href="http://lists.openstack.org/pipermail/openstack-dev/2018-February/127140.html">http://lists.openstack.org/pipermail/openstack-dev/2018-February/127140.html</a><br>
[3]
eavesdrop.openstack.org/meetings/api_sig/2018/api_sig.2018-02-08-16.00.log.html#l-95<br>
[4]
<a class="moz-txt-link-freetext" href="http://eavesdrop.openstack.org/meetings/api_sig/2018/api_sig.2018-02-08-16.00.log.html#l-127">http://eavesdrop.openstack.org/meetings/api_sig/2018/api_sig.2018-02-08-16.00.log.html#l-127</a><br>
[5] <a class="moz-txt-link-freetext" href="https://review.openstack.org/#/c/528801">https://review.openstack.org/#/c/528801</a><br>
</p>
<p>Cheers,<br>
Gilles</p>
<div class="moz-cite-prefix">On 16/03/18 04:30, Chris Dent wrote:<br>
</div>
<blockquote type="cite"
cite="mid:alpine.OSX.2.21.1803151729170.25603@cdent-m01.vmware.com">
<br>
Greetings OpenStack community,
<br>
<br>
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.
<br>
<br>
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.
<br>
<br>
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.
<br>
<br>
As always if you're interested in helping out, in addition to
coming to the meetings, there's also:
<br>
<br>
* The list of bugs [5] indicates several missing or incomplete
guidelines.
<br>
* 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.
<br>
* 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].
<br>
<br>
# Newly Published Guidelines
<br>
<br>
None this week.
<br>
<br>
# API Guidelines Proposed for Freeze
<br>
<br>
Guidelines that are ready for wider review by the whole community.
<br>
<br>
None this week.
<br>
<br>
# Guidelines Currently Under Review [3]
<br>
<br>
* Add guidance on needing cache-control headers
<br>
<a class="moz-txt-link-freetext" href="https://review.openstack.org/550468">https://review.openstack.org/550468</a>
<br>
<br>
* Add guideline on exposing microversions in SDKs
<br>
<a class="moz-txt-link-freetext" href="https://review.openstack.org/#/c/532814/">https://review.openstack.org/#/c/532814/</a>
<br>
<br>
* Add API-schema guide (still being defined)
<br>
<a class="moz-txt-link-freetext" href="https://review.openstack.org/#/c/524467/">https://review.openstack.org/#/c/524467/</a>
<br>
<br>
* A (shrinking) suite of several documents about doing version and
service discovery
<br>
Start at <a class="moz-txt-link-freetext" href="https://review.openstack.org/#/c/459405/">https://review.openstack.org/#/c/459405/</a>
<br>
<br>
* WIP: microversion architecture archival doc (very early; not yet
ready for review)
<br>
<a class="moz-txt-link-freetext" href="https://review.openstack.org/444892">https://review.openstack.org/444892</a>
<br>
<br>
# Highlighting your API impacting issues
<br>
<br>
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.
<br>
<br>
To learn more about the API SIG mission and the work we do, see
our wiki page [4] and guidelines [2].
<br>
<br>
Thanks for reading and see you next week!
<br>
<br>
# References
<br>
<br>
[1]
<a class="moz-txt-link-freetext" href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a>
<br>
[2] <a class="moz-txt-link-freetext" href="http://specs.openstack.org/openstack/api-wg/">http://specs.openstack.org/openstack/api-wg/</a>
<br>
[3]
<a class="moz-txt-link-freetext" href="https://review.openstack.org/#/q/status:open+project:openstack/api-wg,n,z">https://review.openstack.org/#/q/status:open+project:openstack/api-wg,n,z</a><br>
[4] <a class="moz-txt-link-freetext" href="https://wiki.openstack.org/wiki/API_SIG">https://wiki.openstack.org/wiki/API_SIG</a>
<br>
[5] <a class="moz-txt-link-freetext" href="https://bugs.launchpad.net/openstack-api-wg">https://bugs.launchpad.net/openstack-api-wg</a>
<br>
[6] <a class="moz-txt-link-freetext" href="https://git.openstack.org/cgit/openstack/api-wg">https://git.openstack.org/cgit/openstack/api-wg</a>
<br>
[7]
<a class="moz-txt-link-freetext" href="http://specs.openstack.org/openstack/api-wg/guidelines/http.html#http-methods">http://specs.openstack.org/openstack/api-wg/guidelines/http.html#http-methods</a><br>
[8]
<a class="moz-txt-link-freetext" href="http://lists.openstack.org/pipermail/openstack-dev/2018-March/128023.html">http://lists.openstack.org/pipermail/openstack-dev/2018-March/128023.html</a><br>
<br>
Meeting Agenda
<br>
<a class="moz-txt-link-freetext" href="https://wiki.openstack.org/wiki/Meetings/API-SIG#Agenda">https://wiki.openstack.org/wiki/Meetings/API-SIG#Agenda</a>
<br>
Past Meeting Records
<br>
<a class="moz-txt-link-freetext" href="http://eavesdrop.openstack.org/meetings/api_sig/">http://eavesdrop.openstack.org/meetings/api_sig/</a>
<br>
Open Bugs
<br>
<a class="moz-txt-link-freetext" href="https://bugs.launchpad.net/openstack-api-wg">https://bugs.launchpad.net/openstack-api-wg</a>
<br>
<br>
<br>
<fieldset class="mimeAttachmentHeader"></fieldset>
<br>
<pre wrap="">__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: <a class="moz-txt-link-abbreviated" href="mailto:OpenStack-dev-request@lists.openstack.org?subject:unsubscribe">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a>
<a class="moz-txt-link-freetext" href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a>
</pre>
</blockquote>
<br>
<pre class="moz-signature" cols="72">--
Gilles Dubreuil
Senior Software Engineer, Openstack DFG Integration
Mobile: +61 400 894 219
Email: <a class="moz-txt-link-abbreviated" href="mailto:gilles@redhat.com">gilles@redhat.com</a>
GitHub/IRC: gildub
</pre>
</body>
</html>