Re: [openstack-dev] [api] Open API 3.0 for OpenStack API

[Edison Xiang]

Hi team,

I submit a forum [1] named "Cross-project Open API 3.0 support".
We can make more discussions about that in this forum in berlin.
Feel free to add your ideas here [2].
Welcome to join us.
Thanks very much.

[1]
https://www.openstack.org/summit/berlin-2018/summit-schedule/global-search?t=open+api
[2] https://etherpad.openstack.org/p/api-berlin-forum-brainstorming


Best Regards,
Edison Xiang

On Thu, Oct 11, 2018 at 7:48 PM Gilles Dubreuil  wrote:

>
>
> On 11/10/18 00:18, Jeremy Stanley wrote:
>
> On 2018-10-10 13:24:28 +1100 (+1100), Gilles Dubreuil wrote:
>
> On 09/10/18 23:58, Jeremy Stanley wrote:
>
> On 2018-10-09 08:52:52 -0400 (-0400), Jim Rollenhagen wrote:
> [...]
>
> It seems to me that a major goal of openstacksdk is to hide
> differences between clouds from the user. If the user is meant
> to use a GraphQL library themselves, we lose this and the user
> needs to figure it out themselves. Did I understand that
> correctly?
>
> This is especially useful where the SDK implements business
> logic for common operations like "if the user requested A and
> the cloud supports features B+C+D then use those to fulfil the
> request, otherwise fall back to using features E+F".
>
>
> The features offered to the user don't have to change, it's just a
> different architecture.
>
> The user doesn't have to deal with a GraphQL library, only the
> client applications (consuming OpenStack APIs). And there are also
> UI tools such as GraphiQL which allow to interact directly with
> GraphQL servers.
>
>
> My point was simply that SDKs provide more than a simple translation
> of network API calls and feature discovery. There can also be rather
> a lot of "business logic" orchestrating multiple primitive API calls
> to reach some more complex outcome. The services don't want to embed
> this orchestrated business logic themselves, and it makes little
> sense to replicate the same algorithms in every single application
> which wants to make use of such composite functionality. There are
> common actions an application might wish to take which involve
> speaking to multiple APIs for different services to make specific
> calls in a particular order, perhaps feeding the results of one into
> the next.
>
> Can you explain how GraphQL eliminates the above reasons for an SDK?
>
>
> What I meant is the communication part of any SDK interfacing between
> clients and API services can be handled by GraphQL client librairies.
> So instead of having to rely on modules (imported or native) to carry the
> REST communications, we're dealing with data provided by GraphQL libraries
> (which are also modules but standardized as GraphQL is a specification).
> So as you mentioned there is still need to provide the data wrap in
> objects or any adequate struct to present to the consumers.
>
> Having a Schema helps both API and clients developers because the data is
> clearly typed and graphed. Backend devs can focus on resolving the data for
> each node/leaf while the clients can focus on what they need and not how to
> get it.
>
> To relate to $subject, by building the data model (graph) we obtain a
> schema and introspection. That's a big saver in term of resources.
>
>
>
>
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: 
> openstack-dev-requ...@lists.openstack.org?subject:unsubscribehttp://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
>
> __
> 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
>
__
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

Re: [openstack-dev] [api] Open API 3.0 for OpenStack API

[Gilles Dubreuil]

On 11/10/18 00:18, Jeremy Stanley wrote:

On 2018-10-10 13:24:28 +1100 (+1100), Gilles Dubreuil wrote:

On 09/10/18 23:58, Jeremy Stanley wrote:

On 2018-10-09 08:52:52 -0400 (-0400), Jim Rollenhagen wrote:
[...]

It seems to me that a major goal of openstacksdk is to hide
differences between clouds from the user. If the user is meant
to use a GraphQL library themselves, we lose this and the user
needs to figure it out themselves. Did I understand that
correctly?

This is especially useful where the SDK implements business
logic for common operations like "if the user requested A and
the cloud supports features B+C+D then use those to fulfil the
request, otherwise fall back to using features E+F".

The features offered to the user don't have to change, it's just a
different architecture.

The user doesn't have to deal with a GraphQL library, only the
client applications (consuming OpenStack APIs). And there are also
UI tools such as GraphiQL which allow to interact directly with
GraphQL servers.

My point was simply that SDKs provide more than a simple translation
of network API calls and feature discovery. There can also be rather
a lot of "business logic" orchestrating multiple primitive API calls
to reach some more complex outcome. The services don't want to embed
this orchestrated business logic themselves, and it makes little
sense to replicate the same algorithms in every single application
which wants to make use of such composite functionality. There are
common actions an application might wish to take which involve
speaking to multiple APIs for different services to make specific
calls in a particular order, perhaps feeding the results of one into
the next.

Can you explain how GraphQL eliminates the above reasons for an SDK?


What I meant is the communication part of any SDK interfacing between 
clients and API services can be handled by GraphQL client librairies.
So instead of having to rely on modules (imported or native) to carry 
the REST communications, we're dealing with data provided by GraphQL 
libraries (which are also modules but standardized as GraphQL is a 
specification).
So as you mentioned there is still need to provide the data wrap in 
objects or any adequate struct to present to the consumers.


Having a Schema helps both API and clients developers because the data 
is clearly typed and graphed. Backend devs can focus on resolving the 
data for each node/leaf while the clients can focus on what they need 
and not how to get it.


To relate to $subject, by building the data model (graph) we obtain a 
schema and introspection. That's a big saver in term of resources.







__
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


__
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

Re: [openstack-dev] [api] Open API 3.0 for OpenStack API

[Jeremy Stanley]

On 2018-10-10 13:24:28 +1100 (+1100), Gilles Dubreuil wrote:
> On 09/10/18 23:58, Jeremy Stanley wrote:
> > On 2018-10-09 08:52:52 -0400 (-0400), Jim Rollenhagen wrote:
> > [...]
> > > It seems to me that a major goal of openstacksdk is to hide
> > > differences between clouds from the user. If the user is meant
> > > to use a GraphQL library themselves, we lose this and the user
> > > needs to figure it out themselves. Did I understand that
> > > correctly?
> > This is especially useful where the SDK implements business
> > logic for common operations like "if the user requested A and
> > the cloud supports features B+C+D then use those to fulfil the
> > request, otherwise fall back to using features E+F".
> 
> The features offered to the user don't have to change, it's just a
> different architecture.
> 
> The user doesn't have to deal with a GraphQL library, only the
> client applications (consuming OpenStack APIs). And there are also
> UI tools such as GraphiQL which allow to interact directly with
> GraphQL servers.

My point was simply that SDKs provide more than a simple translation
of network API calls and feature discovery. There can also be rather
a lot of "business logic" orchestrating multiple primitive API calls
to reach some more complex outcome. The services don't want to embed
this orchestrated business logic themselves, and it makes little
sense to replicate the same algorithms in every single application
which wants to make use of such composite functionality. There are
common actions an application might wish to take which involve
speaking to multiple APIs for different services to make specific
calls in a particular order, perhaps feeding the results of one into
the next.

Can you explain how GraphQL eliminates the above reasons for an SDK?
-- 
Jeremy Stanley


signature.asc
Description: PGP signature
__
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

Re: [openstack-dev] [api] Open API 3.0 for OpenStack API

[Jim Rollenhagen]

On Tue, Oct 9, 2018 at 10:25 PM Gilles Dubreuil  wrote:

>
>
> On 09/10/18 23:58, Jeremy Stanley wrote:
> > On 2018-10-09 08:52:52 -0400 (-0400), Jim Rollenhagen wrote:
> > [...]
> >> It seems to me that a major goal of openstacksdk is to hide differences
> >> between clouds from the user. If the user is meant to use a GraphQL
> library
> >> themselves, we lose this and the user needs to figure it out themselves.
> >> Did I understand that correctly?
> > This is especially useful where the SDK implements business logic
> > for common operations like "if the user requested A and the cloud
> > supports features B+C+D then use those to fulfil the request,
> > otherwise fall back to using features E+F".
> >
>
> The features offered to the user don't have to change, it's just a
> different architecture.
>
> The user doesn't have to deal with a GraphQL library, only the client
> applications (consuming OpenStack APIs).
> And there are also UI tools such as GraphiQL which allow to interact
> directly with GraphQL servers.
>

Right, this comes back to what I said earlier:

> That said, it seems like using this in a client like OpenStackSDK would
get messy quickly. Instead of asking for which versions are supported,
you'd have to fetch the schema, map it to actual features somehow, and
adjust queries based on this info.
>
> I guess there might be a middleground where we could fetch the REST API
version, and know from that what GraphQL queries can be made.

This isn't unsolvable, but it does sound like quite a bit of work. This
isn't to say "let's not do graphql at all", but it's important to
understand the work involved.

FWIW, I originally mentioned the SDK (as opposed to the clients speaking
graphql directly), as the client applications are currently transitioning
to use openstacksdk instead of their own API calls.

// jim

>
>
> __
> 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
>
__
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

Re: [openstack-dev] [api] Open API 3.0 for OpenStack API

[Gilles Dubreuil]

On 09/10/18 23:58, Jeremy Stanley wrote:

On 2018-10-09 08:52:52 -0400 (-0400), Jim Rollenhagen wrote:
[...]

It seems to me that a major goal of openstacksdk is to hide differences
between clouds from the user. If the user is meant to use a GraphQL library
themselves, we lose this and the user needs to figure it out themselves.
Did I understand that correctly?

This is especially useful where the SDK implements business logic
for common operations like "if the user requested A and the cloud
supports features B+C+D then use those to fulfil the request,
otherwise fall back to using features E+F".



The features offered to the user don't have to change, it's just a 
different architecture.


The user doesn't have to deal with a GraphQL library, only the client 
applications (consuming OpenStack APIs).
And there are also UI tools such as GraphiQL which allow to interact 
directly with GraphQL servers.



__
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

Re: [openstack-dev] [api] Open API 3.0 for OpenStack API

[Jeremy Stanley]

On 2018-10-09 08:52:52 -0400 (-0400), Jim Rollenhagen wrote:
[...]
> It seems to me that a major goal of openstacksdk is to hide differences
> between clouds from the user. If the user is meant to use a GraphQL library
> themselves, we lose this and the user needs to figure it out themselves.
> Did I understand that correctly?

This is especially useful where the SDK implements business logic
for common operations like "if the user requested A and the cloud
supports features B+C+D then use those to fulfil the request,
otherwise fall back to using features E+F".
-- 
Jeremy Stanley


signature.asc
Description: PGP signature
__
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

Re: [openstack-dev] [api] Open API 3.0 for OpenStack API

[Jim Rollenhagen]

On Mon, Oct 8, 2018 at 5:58 AM Gilles Dubreuil  wrote:

>
> On 05/10/18 21:54, Jim Rollenhagen wrote:
>
> GraphQL has introspection features that allow clients to pull the schema
> (types, queries, mutations, etc): https://graphql.org/learn/introspection/
>
> That said, it seems like using this in a client like OpenStackSDK would
> get messy quickly. Instead of asking for which versions are supported,
> you'd have to fetch the schema, map it to actual features somehow, and
> adjust queries based on this info.
>
>
> A main difference in software architecture when using GraphQL is that a
> client makes use of a GraphQL client library instead of relaying on a SDK.
>

It seems to me that a major goal of openstacksdk is to hide differences
between clouds from the user. If the user is meant to use a GraphQL library
themselves, we lose this and the user needs to figure it out themselves.
Did I understand that correctly?

// jim
__
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

Re: [openstack-dev] [api] Open API 3.0 for OpenStack API

[Gilles Dubreuil]

On 05/10/18 21:54, Jim Rollenhagen wrote:
GraphQL has introspection features that allow clients to pull the 
schema (types, queries, mutations, etc): 
https://graphql.org/learn/introspection/


That said, it seems like using this in a client like OpenStackSDK 
would get messy quickly. Instead of asking for which versions are 
supported, you'd have to fetch the schema, map it to actual features 
somehow, and adjust queries based on this info.




A main difference in software architecture when using GraphQL is that a 
client makes use of a GraphQL client library instead of relaying on a SDK.



I guess there might be a middleground where we could fetch the REST 
API version, and know from that what GraphQL queries can be made.


// jim



__
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

Re: [openstack-dev] [api] Open API 3.0 for OpenStack API

[Jim Rollenhagen]

GraphQL has introspection features that allow clients to pull the schema
(types, queries, mutations, etc): https://graphql.org/learn/introspection/

That said, it seems like using this in a client like OpenStackSDK would get
messy quickly. Instead of asking for which versions are supported, you'd
have to fetch the schema, map it to actual features somehow, and adjust
queries based on this info.

I guess there might be a middleground where we could fetch the REST API
version, and know from that what GraphQL queries can be made.

// jim


On Fri, Oct 5, 2018 at 7:30 AM Doug Hellmann  wrote:

> Gilles Dubreuil  writes:
>
> >> About the micro version, we discuss with your team mate dmitry in
> >> another email [1]
> >
> > Obviously micro version is a point of contention.
> > My take on this is because consuming them has been proven harder than
> > developing them.
> > The beauty of GraphQL is that there is no need to deal with version at
> all.
> > New fields appears when needed and old one are marked deprecated.
>
> How does someone using GraphQL to use a cloud know when a specific field
> is available? How can they differentiate what is supported in one cloud
> from what is supported in another, running a different version of the
> same service?
>
> Doug
>
> __
> 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
>
__
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

Re: [openstack-dev] [api] Open API 3.0 for OpenStack API

[Doug Hellmann]

Gilles Dubreuil  writes:

>> About the micro version, we discuss with your team mate dmitry in 
>> another email [1]
>
> Obviously micro version is a point of contention.
> My take on this is because consuming them has been proven harder than 
> developing them.
> The beauty of GraphQL is that there is no need to deal with version at all.
> New fields appears when needed and old one are marked deprecated.

How does someone using GraphQL to use a cloud know when a specific field
is available? How can they differentiate what is supported in one cloud
from what is supported in another, running a different version of the
same service?

Doug

__
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

Re: [openstack-dev] [api] Open API 3.0 for OpenStack API

[Gilles Dubreuil]

Hi Edison,

Sorry for the delay.

Please see inline...

Cheers,
Gilles

On 07/09/18 12:03, Edison Xiang wrote:

Hey gilles,

Thanks your introduction for GraphQL and Relay.

> GraphQL and OpenAPI have a different feature scope and both have pros and 
cons.

I totally agree with you. They can work together.
Right now, I think we have no more work to adapt OpenStack APIs for 
Open API.
Firstly we could sort out Open API schemas base on the current 
OpenStack APIs.

and then we can discuss how to use it.


I think a big question is going to be about the effort required to bring 
OpenStack API to be Open API v3.0 compliant.
This is challenging because the various projects involved and the need 
to validate a new solution across all the projects.
The best approach is likely to first demonstrate a new solution is 
viable and then eventually bring it to be accepted globally.
Also because we don't have unlimited resources, I doubt we're going to 
be able to bring both Open API and GraphQL to the table(s).


There no doubts how OpenStack APIs can benefit from features such as 
schema definitions, self documentation and better performance especially 
if they are built-in or derived from a standard.
Meanwhile a practical example shows those features in action (for the 
skeptical) but also demonstrate how to do it which clarify the effort 
involved along with pros and cons.I want to make clear that I'm not 
against OpenAPI, I was actually keen to get it on board because of the 
benefits


And it will also helps compare solutions (Open API, GraphQL).

So, what do you think about an Open API proof of concept with Neutron?


About the micro version, we discuss with your team mate dmitry in 
another email [1]


Obviously micro version is a point of contention.
My take on this is because consuming them has been proven harder than 
developing them.

The beauty of GraphQL is that there is no need to deal with version at all.
New fields appears when needed and old one are marked deprecated.




[1] 
http://lists.openstack.org/pipermail/openstack-dev/2018-September/134202.html


Best Regards,
Edison Xiang

On Tue, Sep 4, 2018 at 8:37 AM Gilles Dubreuil > wrote:




On 30/08/18 13:56, Edison Xiang wrote:

Hi Ed Leafe,

Thanks your reply.
Open API defines a standard interface description for REST APIs.
Open API 3.0 can make a description(schema) for current OpenStack
REST API.
It will not change current OpenStack API.
I am not a GraphQL expert. I look up something about GraphQL.
In my understanding, GraphQL will get current OpenAPI together
and provide another APIs based on Relay,


Not sure what you mean here, could you please develop?



and Open API is used to describe REST APIs and GraphQL is used to
describe Relay APIs.


There is no such thing as "Relay APIs".
GraphQL povides a de-facto API Schema and Relay provides
extensions on top to facilitate re-fetching, paging and more.
GraphQL and OpenAPI have a different feature scope and both have
pros and cons.
GraphQL is delivering API without using REST verbs as all requests
are undone using POST and its data.
Beyond that what would be great (and it will ultimately come) is
to have both of them working together.

The idea of the GraphQL Proof of Concept is see what it can bring
and at what cost such as effort and trade-offs.
And to compare this against the effort to adapt OpenStack APIs to
use Open API.

BTW what's the status of Open API 3.0 in regards of Microversion?

Regards,
Gilles



Best Regards,
Edison Xiang

On Wed, Aug 29, 2018 at 9:33 PM Ed Leafe mailto:e...@leafe.com>> wrote:

On Aug 29, 2018, at 1:36 AM, Edison Xiang
mailto:xiang.edi...@gmail.com>> wrote:
>
> As we know, Open API 3.0 was released on July, 2017, it is
about one year ago.
> Open API 3.0 support some new features like anyof, oneof
and allof than Open API 2.0(Swagger 2.0).
> Now OpenStack projects do not support Open API.
> Also I found some old emails in the Mail List about
supporting Open API 2.0 in OpenStack.

There is currently an effort by some developers to
investigate the possibility of using GraphQL with OpenStack
APIs. What would Open API 3.0 provide that GraphQL would not?
I’m asking because I don’t know enough about Open API to
compare them.


-- Ed Leafe







__
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

Re: [openstack-dev] [api] Open API 3.0 for OpenStack API

[Edison Xiang]

Hey gilles,

Thanks your introduction for GraphQL and Relay.

> GraphQL and OpenAPI have a different feature scope and both have pros and
cons.

I totally agree with you. They can work together.
Right now, I think we have no more work to adapt OpenStack APIs for Open
API.
Firstly we could sort out Open API schemas base on the current OpenStack
APIs.
and then we can discuss how to use it.
About the micro version, we discuss with your team mate dmitry in another
email [1]

[1]
http://lists.openstack.org/pipermail/openstack-dev/2018-September/134202.html

Best Regards,
Edison Xiang

On Tue, Sep 4, 2018 at 8:37 AM Gilles Dubreuil  wrote:

>
>
> On 30/08/18 13:56, Edison Xiang wrote:
>
> Hi Ed Leafe,
>
> Thanks your reply.
> Open API defines a standard interface description for REST APIs.
> Open API 3.0 can make a description(schema) for current OpenStack REST API.
> It will not change current OpenStack API.
> I am not a GraphQL expert. I look up something about GraphQL.
> In my understanding, GraphQL will get current OpenAPI together and provide
> another APIs based on Relay,
>
>
> Not sure what you mean here, could you please develop?
>
>
> and Open API is used to describe REST APIs and GraphQL is used to describe
> Relay APIs.
>
>
> There is no such thing as "Relay APIs".
> GraphQL povides a de-facto API Schema and Relay provides extensions on top
> to facilitate re-fetching, paging and more.
> GraphQL and OpenAPI have a different feature scope and both have pros and
> cons.
> GraphQL is delivering API without using REST verbs as all requests are
> undone using POST and its data.
> Beyond that what would be great (and it will ultimately come) is to have
> both of them working together.
>
> The idea of the GraphQL Proof of Concept is see what it can bring and at
> what cost such as effort and trade-offs.
> And to compare this against the effort to adapt OpenStack APIs to use Open
> API.
>
> BTW what's the status of Open API 3.0 in regards of Microversion?
>
> Regards,
> Gilles
>
>
> Best Regards,
> Edison Xiang
>
> On Wed, Aug 29, 2018 at 9:33 PM Ed Leafe  wrote:
>
>> On Aug 29, 2018, at 1:36 AM, Edison Xiang  wrote:
>> >
>> > As we know, Open API 3.0 was released on July, 2017, it is about one
>> year ago.
>> > Open API 3.0 support some new features like anyof, oneof and allof than
>> Open API 2.0(Swagger 2.0).
>> > Now OpenStack projects do not support Open API.
>> > Also I found some old emails in the Mail List about supporting Open API
>> 2.0 in OpenStack.
>>
>> There is currently an effort by some developers to investigate the
>> possibility of using GraphQL with OpenStack APIs. What would Open API 3.0
>> provide that GraphQL would not? I’m asking because I don’t know enough
>> about Open API to compare them.
>>
>>
>> -- Ed Leafe
>>
>>
>>
>>
>>
>>
>> __
>> 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
>>
>
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: 
> openstack-dev-requ...@lists.openstack.org?subject:unsubscribehttp://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
> --
> Gilles Dubreuil
> Senior Software Engineer - Red Hat - Openstack DFG Integration
> Email: gil...@redhat.com
> GitHub/IRC: gildub
> Mobile: +61 400 894 219
>
>
>
__
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

Re: [openstack-dev] [api] Open API 3.0 for OpenStack API

[Edison Xiang]

Hi Dmitry,

Thanks your reply. Absolutely you are a sdk expert.

> This is a good first step, but if I get it right it does not specify
which
> response corresponds to which request.

You got it. I think it depends on how to use the API schemas.
We could define some rules to make sure which response corresponds to which
request.
For example, by order. Maybe you can give some other suggestions.
Also, this is not fresh concept, we can find the choice definition in xsd
[1].
By the way, firstly we can sort out OpenStack API schemas ,
and handle these schemas to the developers and the users,
and let them to choose how to use it.

[1] https://www.w3schools.com/xml/el_choice.asp

Best Regards,
Edison Xiang

On Tue, Sep 4, 2018 at 7:01 PM Dmitry Tantsur  wrote:

> Hi,
>
> On 08/29/2018 08:36 AM, Edison Xiang wrote:
> > Hi team,
> >
> > As we know, Open API 3.0 was released on July, 2017, it is about one
> year ago.
> > Open API 3.0 support some new features like anyof, oneof and allof than
> Open API
> > 2.0(Swagger 2.0).
> > Now OpenStack projects do not support Open API.
> > Also I found some old emails in the Mail List about supporting Open API
> 2.0 in
> > OpenStack.
> >
> > Some limitations are mentioned in the Mail List for OpenStack API:
> > 1. The POST */action APIs.
> >  These APIs are exist in lots of projects like nova, cinder.
> >  These APIs have the same URI but the responses will be different
> when the
> > request is different.
> > 2. Micro versions.
> >  These are controller via headers, which are sometimes used to
> describe
> > behavioral changes in an API, not just request/response schema changes.
> >
> > About the first limitation, we can find the solution in the Open API 3.0.
> > The example [2] shows that we can define different request/response in
> the same
> > URI by anyof feature in Open API 3.0.
>
> This is a good first step, but if I get it right it does not specify which
> response corresponds to which request.
>
> >
> > About the micro versions problem, I think it is not a limitation related
> a
> > special API Standard.
> > We can list all micro versions API schema files in one directory like
> nova/V2,
>
> I don't think this approach will scale if you plan to generate anything
> based on
> these schemes. If you generate client code from separate schema files,
> you'll
> essentially end up with dozens of major versions.
>
> > or we can list the schema changes between micro versions as tempest
> project did [3].
>
> ++
>
> >
> > Based on Open API 3.0, it can bring lots of benefits for OpenStack
> Community and
> > does not impact the current features the Community has.
> > For example, we can automatically generate API documents, different
> language
> > Clients(SDK) maybe for different micro versions,
>
>  From my experience with writing an SDK, I don't believe generating a
> complete
> SDK from API schemes is useful. Maybe generating low-level protocol code
> to base
> an SDK on, but even that may be easier to do by hand.
>
> Dmitry
>
> > and generate cloud tool adapters for OpenStack, like ansible module,
> terraform
> > providers and so on.
> > Also we can make an API UI to provide an online and visible API search,
> API
> > Calling for every OpenStack API.
> > 3rd party developers can also do some self-defined development.
> >
> > [1] https://github.com/OAI/OpenAPI-Specification
> > [2]
> >
> https://github.com/edisonxiang/OpenAPI-Specification/blob/master/examples/v3.0/petstore.yaml#L94-L109
> > [3]
> >
> https://github.com/openstack/tempest/tree/master/tempest/lib/api_schema/response/compute
> >
> > Best Regards,
> > Edison Xiang
> >
> >
> >
> >
> __
> > 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
> >
>
>
> __
> 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
>
__
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

Re: [openstack-dev] [api] Open API 3.0 for OpenStack API

[Dmitry Tantsur]

Hi,

On 08/29/2018 08:36 AM, Edison Xiang wrote:

Hi team,

As we know, Open API 3.0 was released on July, 2017, it is about one year ago.
Open API 3.0 support some new features like anyof, oneof and allof than Open API 
2.0(Swagger 2.0).

Now OpenStack projects do not support Open API.
Also I found some old emails in the Mail List about supporting Open API 2.0 in 
OpenStack.


Some limitations are mentioned in the Mail List for OpenStack API:
1. The POST */action APIs.
     These APIs are exist in lots of projects like nova, cinder.
     These APIs have the same URI but the responses will be different when the 
request is different.

2. Micro versions.
     These are controller via headers, which are sometimes used to describe 
behavioral changes in an API, not just request/response schema changes.


About the first limitation, we can find the solution in the Open API 3.0.
The example [2] shows that we can define different request/response in the same 
URI by anyof feature in Open API 3.0.


This is a good first step, but if I get it right it does not specify which 
response corresponds to which request.




About the micro versions problem, I think it is not a limitation related a 
special API Standard.

We can list all micro versions API schema files in one directory like nova/V2,


I don't think this approach will scale if you plan to generate anything based on 
these schemes. If you generate client code from separate schema files, you'll 
essentially end up with dozens of major versions.



or we can list the schema changes between micro versions as tempest project did 
[3].


++



Based on Open API 3.0, it can bring lots of benefits for OpenStack Community and 
does not impact the current features the Community has.
For example, we can automatically generate API documents, different language 
Clients(SDK) maybe for different micro versions,


From my experience with writing an SDK, I don't believe generating a complete 
SDK from API schemes is useful. Maybe generating low-level protocol code to base 
an SDK on, but even that may be easier to do by hand.


Dmitry

and generate cloud tool adapters for OpenStack, like ansible module, terraform 
providers and so on.
Also we can make an API UI to provide an online and visible API search, API 
Calling for every OpenStack API.

3rd party developers can also do some self-defined development.

[1] https://github.com/OAI/OpenAPI-Specification
[2] 
https://github.com/edisonxiang/OpenAPI-Specification/blob/master/examples/v3.0/petstore.yaml#L94-L109
[3] 
https://github.com/openstack/tempest/tree/master/tempest/lib/api_schema/response/compute


Best Regards,
Edison Xiang



__
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




__
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

Re: [openstack-dev] [api] Open API 3.0 for OpenStack API

[Gilles Dubreuil]

On 30/08/18 13:56, Edison Xiang wrote:

Hi Ed Leafe,

Thanks your reply.
Open API defines a standard interface description for REST APIs.
Open API 3.0 can make a description(schema) for current OpenStack REST 
API.

It will not change current OpenStack API.
I am not a GraphQL expert. I look up something about GraphQL.
In my understanding, GraphQL will get current OpenAPI together and 
provide another APIs based on Relay,


Not sure what you mean here, could you please develop?


and Open API is used to describe REST APIs and GraphQL is used to 
describe Relay APIs.


There is no such thing as "Relay APIs".
GraphQL povides a de-facto API Schema and Relay provides extensions on 
top to facilitate re-fetching, paging and more.
GraphQL and OpenAPI have a different feature scope and both have pros 
and cons.
GraphQL is delivering API without using REST verbs as all requests are 
undone using POST and its data.
Beyond that what would be great (and it will ultimately come) is to have 
both of them working together.


The idea of the GraphQL Proof of Concept is see what it can bring and at 
what cost such as effort and trade-offs.
And to compare this against the effort to adapt OpenStack APIs to use 
Open API.


BTW what's the status of Open API 3.0 in regards of Microversion?

Regards,
Gilles



Best Regards,
Edison Xiang

On Wed, Aug 29, 2018 at 9:33 PM Ed Leafe > wrote:


On Aug 29, 2018, at 1:36 AM, Edison Xiang mailto:xiang.edi...@gmail.com>> wrote:
>
> As we know, Open API 3.0 was released on July, 2017, it is about
one year ago.
> Open API 3.0 support some new features like anyof, oneof and
allof than Open API 2.0(Swagger 2.0).
> Now OpenStack projects do not support Open API.
> Also I found some old emails in the Mail List about supporting
Open API 2.0 in OpenStack.

There is currently an effort by some developers to investigate the
possibility of using GraphQL with OpenStack APIs. What would Open
API 3.0 provide that GraphQL would not? I’m asking because I don’t
know enough about Open API to compare them.


-- Ed Leafe






__
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



__
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 - Red Hat - Openstack DFG Integration
Email: gil...@redhat.com
GitHub/IRC: gildub
Mobile: +61 400 894 219

__
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

Re: [openstack-dev] [api] Open API 3.0 for OpenStack API

[Edison Xiang]

Hey doug,

Thanks your reply. Very good question.
It is not a conflict with current API Documents work that has already been
done.
We can use some tools to generate Open API schema from existing machine
readable API-def in every project like nova [1]
We can still use the existing tools to generate the API Documents website.

[1] https://github.com/openstack/nova/tree/master/api-ref/source

Best Regards,
Edison Xiang

On Fri, Aug 31, 2018 at 1:46 AM Doug Hellmann  wrote:

> Excerpts from Edison Xiang's message of 2018-08-30 14:08:12 +0800:
> > Hey dims,
> >
> > Thanks your reply. Your suggestion is very important.
> >
> > > what would be the impact to projects?
> > > what steps they would have to take?
> >
> > We can launch a project to publish OpenStack Projects APIs Schema for
> users
> > and  developers.
> > But now OpenStack Projects have no APIs Schema definition.
> > Open API will not impact OpenStack Projects features they have,
> > but we need some volunteers to define every project APIs Schema by Open
> API
> > 3.0.
> >
> > > Do we have a sample/mock API where we can show that the Action and
> > Microversions can be declared to reflect reality and it can actually work
> > with the generated code?
> > Yeah, you can copy this yaml [1] into editor [2] to generate server or
> > client codes or try it out.
> > We can do more demos later.
> >
> > [1]
> >
> https://github.com/edisonxiang/OpenAPI-Specification/blob/master/examples/v3.0/petstore.yaml
> > [2] https://editor.swagger.io
> >
> > Best Regards,
> > Edison Xiang
>
> How does this proposal relate to the work that has already been
> done to build the API guide
> https://developer.openstack.org/api-guide/quick-start/ documentation?
>
> Doug
>
> >
> > On Wed, Aug 29, 2018 at 6:31 PM Davanum Srinivas 
> wrote:
> >
> > > Edison,
> > >
> > > This is definitely a step in the right direction if we can pull it off.
> > >
> > > Given the previous experiences and the current situation of how and
> where
> > > we store the information currently and how we generate the website for
> the
> > > API(s), can you please outline
> > > - what would be the impact to projects?
> > > - what steps they would have to take?
> > >
> > > Also, the whole point of having these definitions is that the generated
> > > code works. Do we have a sample/mock API where we can show that the
> Action
> > > and Microversions can be declared to reflect reality and it can
> actually
> > > work with the generated code?
> > >
> > > Thanks,
> > > Dims
> > >
> > > On Wed, Aug 29, 2018 at 2:37 AM Edison Xiang 
> > > wrote:
> > >
> > >> Hi team,
> > >>
> > >> As we know, Open API 3.0 was released on July, 2017, it is about one
> year
> > >> ago.
> > >> Open API 3.0 support some new features like anyof, oneof and allof
> than
> > >> Open API 2.0(Swagger 2.0).
> > >> Now OpenStack projects do not support Open API.
> > >> Also I found some old emails in the Mail List about supporting Open
> API
> > >> 2.0 in OpenStack.
> > >>
> > >> Some limitations are mentioned in the Mail List for OpenStack API:
> > >> 1. The POST */action APIs.
> > >> These APIs are exist in lots of projects like nova, cinder.
> > >> These APIs have the same URI but the responses will be different
> when
> > >> the request is different.
> > >> 2. Micro versions.
> > >> These are controller via headers, which are sometimes used to
> > >> describe behavioral changes in an API, not just request/response
> schema
> > >> changes.
> > >>
> > >> About the first limitation, we can find the solution in the Open API
> 3.0.
> > >> The example [2] shows that we can define different request/response in
> > >> the same URI by anyof feature in Open API 3.0.
> > >>
> > >> About the micro versions problem, I think it is not a limitation
> related
> > >> a special API Standard.
> > >> We can list all micro versions API schema files in one directory like
> > >> nova/V2,
> > >> or we can list the schema changes between micro versions as tempest
> > >> project did [3].
> > >>
> > >> Based on Open API 3.0, it can bring lots of benefits for OpenStack
> > >> Community and does not impact the current features the  Community has.
> > >> For example, we can automatically generate API documents, different
> > >> language Clients(SDK) maybe for different micro versions,
> > >> and generate cloud tool adapters for OpenStack, like ansible module,
> > >> terraform providers and so on.
> > >> Also we can make an API UI to provide an online and visible API
> search,
> > >> API Calling for every OpenStack API.
> > >> 3rd party developers can also do some self-defined development.
> > >>
> > >> [1] https://github.com/OAI/OpenAPI-Specification
> > >> [2]
> > >>
> https://github.com/edisonxiang/OpenAPI-Specification/blob/master/examples/v3.0/petstore.yaml#L94-L109
> > >> [3]
> > >>
> https://github.com/openstack/tempest/tree/master/tempest/lib/api_schema/response/compute
> > >>
> > >> Best Regards,
> > >> Edison Xiang
> > >>
> > >>
> 

Re: [openstack-dev] [api] Open API 3.0 for OpenStack API

[Doug Hellmann]

Excerpts from Edison Xiang's message of 2018-08-30 14:08:12 +0800:
> Hey dims,
> 
> Thanks your reply. Your suggestion is very important.
> 
> > what would be the impact to projects?
> > what steps they would have to take?
> 
> We can launch a project to publish OpenStack Projects APIs Schema for users
> and  developers.
> But now OpenStack Projects have no APIs Schema definition.
> Open API will not impact OpenStack Projects features they have,
> but we need some volunteers to define every project APIs Schema by Open API
> 3.0.
> 
> > Do we have a sample/mock API where we can show that the Action and
> Microversions can be declared to reflect reality and it can actually work
> with the generated code?
> Yeah, you can copy this yaml [1] into editor [2] to generate server or
> client codes or try it out.
> We can do more demos later.
> 
> [1]
> https://github.com/edisonxiang/OpenAPI-Specification/blob/master/examples/v3.0/petstore.yaml
> [2] https://editor.swagger.io
> 
> Best Regards,
> Edison Xiang

How does this proposal relate to the work that has already been
done to build the API guide
https://developer.openstack.org/api-guide/quick-start/ documentation?

Doug

> 
> On Wed, Aug 29, 2018 at 6:31 PM Davanum Srinivas  wrote:
> 
> > Edison,
> >
> > This is definitely a step in the right direction if we can pull it off.
> >
> > Given the previous experiences and the current situation of how and where
> > we store the information currently and how we generate the website for the
> > API(s), can you please outline
> > - what would be the impact to projects?
> > - what steps they would have to take?
> >
> > Also, the whole point of having these definitions is that the generated
> > code works. Do we have a sample/mock API where we can show that the Action
> > and Microversions can be declared to reflect reality and it can actually
> > work with the generated code?
> >
> > Thanks,
> > Dims
> >
> > On Wed, Aug 29, 2018 at 2:37 AM Edison Xiang 
> > wrote:
> >
> >> Hi team,
> >>
> >> As we know, Open API 3.0 was released on July, 2017, it is about one year
> >> ago.
> >> Open API 3.0 support some new features like anyof, oneof and allof than
> >> Open API 2.0(Swagger 2.0).
> >> Now OpenStack projects do not support Open API.
> >> Also I found some old emails in the Mail List about supporting Open API
> >> 2.0 in OpenStack.
> >>
> >> Some limitations are mentioned in the Mail List for OpenStack API:
> >> 1. The POST */action APIs.
> >> These APIs are exist in lots of projects like nova, cinder.
> >> These APIs have the same URI but the responses will be different when
> >> the request is different.
> >> 2. Micro versions.
> >> These are controller via headers, which are sometimes used to
> >> describe behavioral changes in an API, not just request/response schema
> >> changes.
> >>
> >> About the first limitation, we can find the solution in the Open API 3.0.
> >> The example [2] shows that we can define different request/response in
> >> the same URI by anyof feature in Open API 3.0.
> >>
> >> About the micro versions problem, I think it is not a limitation related
> >> a special API Standard.
> >> We can list all micro versions API schema files in one directory like
> >> nova/V2,
> >> or we can list the schema changes between micro versions as tempest
> >> project did [3].
> >>
> >> Based on Open API 3.0, it can bring lots of benefits for OpenStack
> >> Community and does not impact the current features the  Community has.
> >> For example, we can automatically generate API documents, different
> >> language Clients(SDK) maybe for different micro versions,
> >> and generate cloud tool adapters for OpenStack, like ansible module,
> >> terraform providers and so on.
> >> Also we can make an API UI to provide an online and visible API search,
> >> API Calling for every OpenStack API.
> >> 3rd party developers can also do some self-defined development.
> >>
> >> [1] https://github.com/OAI/OpenAPI-Specification
> >> [2]
> >> https://github.com/edisonxiang/OpenAPI-Specification/blob/master/examples/v3.0/petstore.yaml#L94-L109
> >> [3]
> >> https://github.com/openstack/tempest/tree/master/tempest/lib/api_schema/response/compute
> >>
> >> Best Regards,
> >> Edison Xiang
> >>
> >> __
> >> 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
> >>
> >
> >
> > --
> > Davanum Srinivas :: https://twitter.com/dims
> > __
> > 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
> >

__

Re: [openstack-dev] [api] Open API 3.0 for OpenStack API

[Edison Xiang]

Hey dims,

Thanks your reply. Your suggestion is very important.

> what would be the impact to projects?
> what steps they would have to take?

We can launch a project to publish OpenStack Projects APIs Schema for users
and  developers.
But now OpenStack Projects have no APIs Schema definition.
Open API will not impact OpenStack Projects features they have,
but we need some volunteers to define every project APIs Schema by Open API
3.0.

> Do we have a sample/mock API where we can show that the Action and
Microversions can be declared to reflect reality and it can actually work
with the generated code?
Yeah, you can copy this yaml [1] into editor [2] to generate server or
client codes or try it out.
We can do more demos later.

[1]
https://github.com/edisonxiang/OpenAPI-Specification/blob/master/examples/v3.0/petstore.yaml
[2] https://editor.swagger.io

Best Regards,
Edison Xiang

On Wed, Aug 29, 2018 at 6:31 PM Davanum Srinivas  wrote:

> Edison,
>
> This is definitely a step in the right direction if we can pull it off.
>
> Given the previous experiences and the current situation of how and where
> we store the information currently and how we generate the website for the
> API(s), can you please outline
> - what would be the impact to projects?
> - what steps they would have to take?
>
> Also, the whole point of having these definitions is that the generated
> code works. Do we have a sample/mock API where we can show that the Action
> and Microversions can be declared to reflect reality and it can actually
> work with the generated code?
>
> Thanks,
> Dims
>
> On Wed, Aug 29, 2018 at 2:37 AM Edison Xiang 
> wrote:
>
>> Hi team,
>>
>> As we know, Open API 3.0 was released on July, 2017, it is about one year
>> ago.
>> Open API 3.0 support some new features like anyof, oneof and allof than
>> Open API 2.0(Swagger 2.0).
>> Now OpenStack projects do not support Open API.
>> Also I found some old emails in the Mail List about supporting Open API
>> 2.0 in OpenStack.
>>
>> Some limitations are mentioned in the Mail List for OpenStack API:
>> 1. The POST */action APIs.
>> These APIs are exist in lots of projects like nova, cinder.
>> These APIs have the same URI but the responses will be different when
>> the request is different.
>> 2. Micro versions.
>> These are controller via headers, which are sometimes used to
>> describe behavioral changes in an API, not just request/response schema
>> changes.
>>
>> About the first limitation, we can find the solution in the Open API 3.0.
>> The example [2] shows that we can define different request/response in
>> the same URI by anyof feature in Open API 3.0.
>>
>> About the micro versions problem, I think it is not a limitation related
>> a special API Standard.
>> We can list all micro versions API schema files in one directory like
>> nova/V2,
>> or we can list the schema changes between micro versions as tempest
>> project did [3].
>>
>> Based on Open API 3.0, it can bring lots of benefits for OpenStack
>> Community and does not impact the current features the  Community has.
>> For example, we can automatically generate API documents, different
>> language Clients(SDK) maybe for different micro versions,
>> and generate cloud tool adapters for OpenStack, like ansible module,
>> terraform providers and so on.
>> Also we can make an API UI to provide an online and visible API search,
>> API Calling for every OpenStack API.
>> 3rd party developers can also do some self-defined development.
>>
>> [1] https://github.com/OAI/OpenAPI-Specification
>> [2]
>> https://github.com/edisonxiang/OpenAPI-Specification/blob/master/examples/v3.0/petstore.yaml#L94-L109
>> [3]
>> https://github.com/openstack/tempest/tree/master/tempest/lib/api_schema/response/compute
>>
>> Best Regards,
>> Edison Xiang
>>
>> __
>> 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
>>
>
>
> --
> Davanum Srinivas :: https://twitter.com/dims
> __
> 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
>
__
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

Re: [openstack-dev] [api] Open API 3.0 for OpenStack API

[Edison Xiang]

Hi Jay,

Thanks your reply.

As we know, we can automatically generate API Documents, different language
of Clients(SDK),
cloud tool adapters for OpenStack based on Open API 3.0 Schema.

About the other self-defined development for 3rd party developers,
based on the Open API 3.0 schema, developers can develop UI for API online
search, API online calling.
or directly call OpenStack API that it does not need Clients(SDK),
or self-defined API Documents and so on.
Since there is a good ecosystem around Open API,
developers can do whatever they want based on Open API 3.0 schema.

Best Regards,
Edison Xiang

On Wed, Aug 29, 2018 at 8:12 PM Jay Pipes  wrote:

> On 08/29/2018 02:36 AM, Edison Xiang wrote:
> > Based on Open API 3.0, it can bring lots of benefits for OpenStack
> > Community and does not impact the current features the Community has.
> 
> > 3rd party developers can also do some self-defined development.
>
> Hi Edison,
>
> Would you mind expanding on what you are referring to with the above
> line about 3rd party developers doing self-defined development?
>
> Thanks!
> -jay
>
> __
> 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
>
__
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

Re: [openstack-dev] [api] Open API 3.0 for OpenStack API

[Edison Xiang]

Hi Ed Leafe,

Thanks your reply.
Open API defines a standard interface description for REST APIs.
Open API 3.0 can make a description(schema) for current OpenStack REST API.
It will not change current OpenStack API.
I am not a GraphQL expert. I look up something about GraphQL.
In my understanding, GraphQL will get current OpenAPI together and provide
another APIs based on Relay,
and Open API is used to describe REST APIs and GraphQL is used to describe
Relay APIs.

Best Regards,
Edison Xiang

On Wed, Aug 29, 2018 at 9:33 PM Ed Leafe  wrote:

> On Aug 29, 2018, at 1:36 AM, Edison Xiang  wrote:
> >
> > As we know, Open API 3.0 was released on July, 2017, it is about one
> year ago.
> > Open API 3.0 support some new features like anyof, oneof and allof than
> Open API 2.0(Swagger 2.0).
> > Now OpenStack projects do not support Open API.
> > Also I found some old emails in the Mail List about supporting Open API
> 2.0 in OpenStack.
>
> There is currently an effort by some developers to investigate the
> possibility of using GraphQL with OpenStack APIs. What would Open API 3.0
> provide that GraphQL would not? I’m asking because I don’t know enough
> about Open API to compare them.
>
>
> -- Ed Leafe
>
>
>
>
>
>
> __
> 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
>
__
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

Re: [openstack-dev] [api] Open API 3.0 for OpenStack API

[Ed Leafe]

On Aug 29, 2018, at 1:36 AM, Edison Xiang  wrote:
> 
> As we know, Open API 3.0 was released on July, 2017, it is about one year ago.
> Open API 3.0 support some new features like anyof, oneof and allof than Open 
> API 2.0(Swagger 2.0).
> Now OpenStack projects do not support Open API.
> Also I found some old emails in the Mail List about supporting Open API 2.0 
> in OpenStack.

There is currently an effort by some developers to investigate the possibility 
of using GraphQL with OpenStack APIs. What would Open API 3.0 provide that 
GraphQL would not? I’m asking because I don’t know enough about Open API to 
compare them.


-- Ed Leafe






__
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

Re: [openstack-dev] [api] Open API 3.0 for OpenStack API

[Jay Pipes]

On 08/29/2018 02:36 AM, Edison Xiang wrote:
Based on Open API 3.0, it can bring lots of benefits for OpenStack 
Community and does not impact the current features the Community has.



3rd party developers can also do some self-defined development.


Hi Edison,

Would you mind expanding on what you are referring to with the above 
line about 3rd party developers doing self-defined development?


Thanks!
-jay

__
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

Re: [openstack-dev] [api] Open API 3.0 for OpenStack API

[Davanum Srinivas]

Edison,

This is definitely a step in the right direction if we can pull it off.

Given the previous experiences and the current situation of how and where
we store the information currently and how we generate the website for the
API(s), can you please outline
- what would be the impact to projects?
- what steps they would have to take?

Also, the whole point of having these definitions is that the generated
code works. Do we have a sample/mock API where we can show that the Action
and Microversions can be declared to reflect reality and it can actually
work with the generated code?

Thanks,
Dims

On Wed, Aug 29, 2018 at 2:37 AM Edison Xiang  wrote:

> Hi team,
>
> As we know, Open API 3.0 was released on July, 2017, it is about one year
> ago.
> Open API 3.0 support some new features like anyof, oneof and allof than
> Open API 2.0(Swagger 2.0).
> Now OpenStack projects do not support Open API.
> Also I found some old emails in the Mail List about supporting Open API
> 2.0 in OpenStack.
>
> Some limitations are mentioned in the Mail List for OpenStack API:
> 1. The POST */action APIs.
> These APIs are exist in lots of projects like nova, cinder.
> These APIs have the same URI but the responses will be different when
> the request is different.
> 2. Micro versions.
> These are controller via headers, which are sometimes used to describe
> behavioral changes in an API, not just request/response schema changes.
>
> About the first limitation, we can find the solution in the Open API 3.0.
> The example [2] shows that we can define different request/response in the
> same URI by anyof feature in Open API 3.0.
>
> About the micro versions problem, I think it is not a limitation related a
> special API Standard.
> We can list all micro versions API schema files in one directory like
> nova/V2,
> or we can list the schema changes between micro versions as tempest
> project did [3].
>
> Based on Open API 3.0, it can bring lots of benefits for OpenStack
> Community and does not impact the current features the  Community has.
> For example, we can automatically generate API documents, different
> language Clients(SDK) maybe for different micro versions,
> and generate cloud tool adapters for OpenStack, like ansible module,
> terraform providers and so on.
> Also we can make an API UI to provide an online and visible API search,
> API Calling for every OpenStack API.
> 3rd party developers can also do some self-defined development.
>
> [1] https://github.com/OAI/OpenAPI-Specification
> [2]
> https://github.com/edisonxiang/OpenAPI-Specification/blob/master/examples/v3.0/petstore.yaml#L94-L109
> [3]
> https://github.com/openstack/tempest/tree/master/tempest/lib/api_schema/response/compute
>
> Best Regards,
> Edison Xiang
>
> __
> 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
>


-- 
Davanum Srinivas :: https://twitter.com/dims
__
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

[openstack-dev] [api] Open API 3.0 for OpenStack API

[Edison Xiang]

Hi team,

As we know, Open API 3.0 was released on July, 2017, it is about one year
ago.
Open API 3.0 support some new features like anyof, oneof and allof than
Open API 2.0(Swagger 2.0).
Now OpenStack projects do not support Open API.
Also I found some old emails in the Mail List about supporting Open API 2.0
in OpenStack.

Some limitations are mentioned in the Mail List for OpenStack API:
1. The POST */action APIs.
These APIs are exist in lots of projects like nova, cinder.
These APIs have the same URI but the responses will be different when
the request is different.
2. Micro versions.
These are controller via headers, which are sometimes used to describe
behavioral changes in an API, not just request/response schema changes.

About the first limitation, we can find the solution in the Open API 3.0.
The example [2] shows that we can define different request/response in the
same URI by anyof feature in Open API 3.0.

About the micro versions problem, I think it is not a limitation related a
special API Standard.
We can list all micro versions API schema files in one directory like
nova/V2,
or we can list the schema changes between micro versions as tempest project
did [3].

Based on Open API 3.0, it can bring lots of benefits for OpenStack
Community and does not impact the current features the  Community has.
For example, we can automatically generate API documents, different
language Clients(SDK) maybe for different micro versions,
and generate cloud tool adapters for OpenStack, like ansible module,
terraform providers and so on.
Also we can make an API UI to provide an online and visible API search, API
Calling for every OpenStack API.
3rd party developers can also do some self-defined development.

[1] https://github.com/OAI/OpenAPI-Specification
[2]
https://github.com/edisonxiang/OpenAPI-Specification/blob/master/examples/v3.0/petstore.yaml#L94-L109
[3]
https://github.com/openstack/tempest/tree/master/tempest/lib/api_schema/response/compute

Best Regards,
Edison Xiang
__
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