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-requ...@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: gil...@redhat.com
GitHub/IRC: gildub
__________________________________________________________________________
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
