[openstack-dev] [API-WG] Schema like aws-sdk and API capabilities discovery

Gilles Dubreuil 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 
structure dynamically.
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 [1] & [2] 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
> sure.
Absolutely, I think we're getting there. Thank you for being patient :)

More information about the OpenStack-dev mailing list