[openstack-dev] [API-WG] Schema like aws-sdk and API capabilities discovery
gdubreui at redhat.com
Thu Mar 16 08:15:58 UTC 2017
On 15/03/17 01:21, Chris Dent wrote:
> On Fri, 10 Mar 2017, Gilles Dubreuil wrote:
>> On a different list we're talking about improving/new features on the
>> client side of OpenStack APIs and this one came up (please see below).
>> Although API-ref is doing a great job, I believe the question is: Can
>> we achieve an equivalent of aws-sdk? For instance could we have each
>> project's API to publish its own schema?
> I'm not sure if I fully understand what you're asking about or for?
> Is the request that the various OpenStack APIs publish some kind of
> structure API description (using something like
> https://www.openapis.org/ )? Various people did some exploration of
> this, trying to use swagger (as it was called then) to help with
> documenting the APIs. What we discovered at the time was a) using
> swagger on existing APIs didn't work as well as using it when
> creating new ones, b) microversions and swagger don't play as well
> together as we'd like.
> If you mean something like WADL or WSDL, the general decision has
> been that such things only work if there is sufficient tooling on
> the client side, and we don't want to require our users to have that
> kind of tooling. Instead we'd prefer that the APIs converge toward
> being relatively comprehensible and usable by humans.
> If you mean something else (like perhaps using json-home?) please
> explain what it is.
Yes I meant one of such approaches to be able to retrieve an API
I'm not familiar with WADL or WSDL, but looking at it, I don't see why
it imposes anything on the client side.
What's precludes a client to make a request without having retrieved the
API structure before end?
Anyway, my approach has been very practical, sort of bottom up, using
API-ref to web crawl the API structures.
Look at this to get an idea:
From that experience I believe we must be able to go to the next level.
In any case, the API-WG has not taken upon itself to make any.
> assertions or statements about facilitating client creation
> automation. Our position is that the APIs should be something you
> can consume without a great deal of intermediation and we work
> towards ensuring that. That's not a fixed decision, but is certainly
> the case for now.
Yes and as I said API structures don't have to be used but if available
then we could enter a new automation level.
>> I suppose this would fit under the API-WG umbrella. Would that be
>> correct? Could someone in the group provide feedback please?
> It could well do if we can figure out what we're all talking about
Thanks for taking the time ;)
>> Trying to find current work around this, I can see the API
>> capabilities discovery  &  is great but, it seems to me that
>> part of the challenge for the WG is a lack of schema too. Wouldn't it
>> make sense to have a standardized way for all services APIs (at least
>> on the public side) to publish their schema (including
>> version/microversions details) before going any further?
> The capabilities work is oriented towards determining what features
> are available either "in this cloud" or "on this specific resource".
I understand the capabilities are providing a different feature. From
the current efforts about it, it seems to me that it would benefit from
an API structure advertisement.
> I guess the most important questions I can ask at this point are "Can
> you please define what you mean by schema?" and "If I had one, what
> could I do with it?". That will go a long way to making sure we're
> near to the same page. I can make some guesses, but better to be
Absolutely, I think we're getting there. Thank you for being patient :)
More information about the OpenStack-dev