Re: [openstack-dev] [Keystone][Marconi][Oslo] Discoverable home document for APIs (Was: Re: [Nova][Glance] Support of v1 and v2 glance APIs in Nova)
On Mon, Nov 25, 2013 at 4:25 PM, Jamie Lennox jamielen...@redhat.comwrote:
To most of your questions i don't know the answer as the format was in
place before i started with the project. I know that it is similar (though
not exactly the same) as nova's but not where they are documented (as they
are version independent)
I can tell you it looks like:
{
versions: {
values: [
{
status: stable,
updated: 2013-03-06T00:00:00Z,
media-types: [
{
base: application\/json,
type: application\/vnd.openstack.identity-v3+json
},
{
base: application\/xml,
type: application\/vnd.openstack.identity-v3+xml
}
],
id: v3.0,
links: [
{
href: http:\/\/localhost:5000\/v3\/,
rel: self
}
]
},
{
status: stable,
updated: 2013-03-06T00:00:00Z,
media-types: [
{
base: application\/json,
type: application\/vnd.openstack.identity-v2.0+json
},
{
base: application\/xml,
type: application\/vnd.openstack.identity-v2.0+xml
}
],
id: v2.0,
links: [
{
href: http:\/\/localhost:5000\/v2.0\/,
rel: self
},
{
href: http:\/\/docs.openstack.org
\/api\/openstack-identity-service\/2.0\/content\/,
type: text\/html,
rel: describedby
},
{
href: http:\/\/docs.openstack.org
\/api\/openstack-identity-service\/2.0\/identity-dev-guide-2.0.pdf,
type: application\/pdf,
rel: describedby
}
]
}
]
}
}
The above is keystone's unversioned multiple choice response. I just wrote
docs for v3's existing version description response, which is closely based
on the above:
https://review.openstack.org/#/c/60576/
- Original Message -
From: Flavio Percoco fla...@redhat.com
To: OpenStack Development Mailing List (not for usage questions)
openstack-dev@lists.openstack.org
Sent: Monday, 25 November, 2013 6:41:42 PM
Subject: [openstack-dev] [Keystone][Marconi][Oslo] Discoverable home
document for APIs (Was: Re: [Nova][Glance]
Support of v1 and v2 glance APIs in Nova)
On 25/11/13 09:28 +1000, Jamie Lennox wrote:
So the way we have this in keystone at least is that querying GET / will
return all available API versions and querying /v2.0 for example is a
similar result with just the v2 endpoint. So you can hard pin a version
by using the versioned URL.
I spoke to somebody the other day about the discovery process in
services. The long term goal should be that the service catalog contains
unversioned endpoints and that all clients should do discovery. For
keystone the review has been underway for a while now:
https://review.openstack.org/#/c/38414/ the basics of this should be
able to be moved into OSLO for other projects if required.
Did you guys create your own 'home document' language? or did you base
it on some existing format? Is it documented somewhere? IIRC, there's
a thread where part of this was discussed, it was related to horizon.
I'm curious to know what you guys did and if you knew about
JSON-Home[0] when you started working on this.
We used json-home for Marconi v1 and we'd want the client to work in a
'follow your nose' way. Since, I'd prefer OpenStack modules to use the
same language for this, I'm curious to know why - if so - you
created your own spec, what are the benefits and if it's documented
somewhere.
Cheers,
FF
[0] http://tools.ietf.org/html/draft-nottingham-json-home-02
--
@flaper87
Flavio Percoco
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
--
-Dolph
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Keystone][Marconi][Oslo] Discoverable home document for APIs (Was: Re: [Nova][Glance] Support of v1 and v2 glance APIs in Nova)
On 26/11/13 10:57 -0600, Dolph Mathews wrote: On Tue, Nov 26, 2013 at 2:47 AM, Flavio Percoco fla...@redhat.com wrote: As crazy as it sounds, have you guys considered migrating to Nottingham's approach? It only sounds crazy because I have no idea how to migrate an unversioned endpoint :) Skimming through his proposal, it looks like it might actually be compatible with ours to include side by side? If so, we could support both for a couple releases before moving on. This would be awesome. We'll still have to write a python library for it but that's something we could do as part of Marconi's client development and then move it to its own repo - or oslo - once it's ready. Does this proposal have much traction outside the OpenStack community? (and how much traction does it have within the community already?) It does. I don't have the exact numbers of users but I know for sure the work there is moving forward. A new version will be released soon, AFAIU. Cheers, FF -- @flaper87 Flavio Percoco pgp5LOk44Ranp.pgp Description: PGP signature ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Keystone][Marconi][Oslo] Discoverable home document for APIs (Was: Re: [Nova][Glance] Support of v1 and v2 glance APIs in Nova)
On 25/11/13 16:50 -0600, Dolph Mathews wrote: On Mon, Nov 25, 2013 at 2:41 AM, Flavio Percoco fla...@redhat.com wrote: On 25/11/13 09:28 +1000, Jamie Lennox wrote: So the way we have this in keystone at least is that querying GET / will return all available API versions and querying /v2.0 for example is a similar result with just the v2 endpoint. So you can hard pin a version by using the versioned URL. I spoke to somebody the other day about the discovery process in services. The long term goal should be that the service catalog contains unversioned endpoints and that all clients should do discovery. For keystone the review has been underway for a while now: https://review.openstack.org/#/c/38414/ the basics of this should be able to be moved into OSLO for other projects if required. Did you guys create your own 'home document' language? or did you base it on some existing format? Is it documented somewhere? IIRC, there's a thread where part of this was discussed, it was related to horizon. I'm curious to know what you guys did and if you knew about JSON-Home[0] when you started working on this. It looks like our multiple choice response might predate Nottingham's proposal, but not by much. In keystone, it's been stable since I joined the project, midway through the diablo cycle (summer 2011). I don't know any more history than that, but I've CC'd Jorge Williams, who probably knows. I really like Nottingham's approach of adding relational links from the base endpoint, I've been thinking about doing the same for keystone for quite a while. As crazy as it sounds, have you guys considered migrating to Nottingham's approach? We picked this approach because we didn't want to invent it ourselves and this happens to have a well defined RFC as well. If there's something Nottingham's proposal lacks of, I think we could provide some feedback and help making it better. We used json-home for Marconi v1 and we'd want the client to work in a 'follow your nose' way. Since, I'd prefer OpenStack modules to use the same language for this, I'm curious to know why - if so - you created your own spec, what are the benefits and if it's documented somewhere. Then why didn't Marconi follow the lead of one of the other projects? ;) LOOOL, I knew you were going to say that. I think I knew about you guys having something similar but at some point I most have forgotten about it. That being said, the main rationals were: 1) Using something documented and known upstream made more sense and it also helps getting more contributions from the community. 2) We already knew it, which falls back in point 1. I completely agree though - standardized version discovery across the ecosystem would be fantastic. All that being said, I don't think it would be very hard to migrate Marconi to something common if we agree that json-home is not good enough for OpenStack. Nonetheless, it'd be a shame not to provide feedback to Mark Nottingham about it. So far, his approach has been good enough for us - but, you know, Marconi is still way too small. Is keystone's home schema spec documented somewhere? Cheers, FF -- @flaper87 Flavio Percoco pgpBx9SMtsMIc.pgp Description: PGP signature ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Keystone][Marconi][Oslo] Discoverable home document for APIs (Was: Re: [Nova][Glance] Support of v1 and v2 glance APIs in Nova)
Nottingham's RFC is exceptionally well documented. I would be strongly against Marconi moving from that RFC to any other format unless the alternative was equally well documented. If they were equally well documented, then I would be neutral on changing it. More importantly, if a project is providing discoverability for their API and recommending the use of that to clients, the primary unit and integration tests for the service need to use the discovery mechanism. It doesn't help to provide discoverability if the implementation doesn't actually provide working links in the service descriptor (regardless of the specific format used). Sam -Original Message- From: Flavio Percoco [mailto:fla...@redhat.com] Sent: Tuesday, November 26, 2013 2:47 AM To: OpenStack Development Mailing List (not for usage questions) Cc: Jorge Williams Subject: Re: [openstack-dev] [Keystone][Marconi][Oslo] Discoverable home document for APIs (Was: Re: [Nova][Glance] Support of v1 and v2 glance APIs in Nova) On 25/11/13 16:50 -0600, Dolph Mathews wrote: On Mon, Nov 25, 2013 at 2:41 AM, Flavio Percoco fla...@redhat.com wrote: On 25/11/13 09:28 +1000, Jamie Lennox wrote: So the way we have this in keystone at least is that querying GET / will return all available API versions and querying /v2.0 for example is a similar result with just the v2 endpoint. So you can hard pin a version by using the versioned URL. I spoke to somebody the other day about the discovery process in services. The long term goal should be that the service catalog contains unversioned endpoints and that all clients should do discovery. For keystone the review has been underway for a while now: https://review.openstack.org/#/c/38414/ the basics of this should be able to be moved into OSLO for other projects if required. Did you guys create your own 'home document' language? or did you base it on some existing format? Is it documented somewhere? IIRC, there's a thread where part of this was discussed, it was related to horizon. I'm curious to know what you guys did and if you knew about JSON-Home[0] when you started working on this. It looks like our multiple choice response might predate Nottingham's proposal, but not by much. In keystone, it's been stable since I joined the project, midway through the diablo cycle (summer 2011). I don't know any more history than that, but I've CC'd Jorge Williams, who probably knows. I really like Nottingham's approach of adding relational links from the base endpoint, I've been thinking about doing the same for keystone for quite a while. As crazy as it sounds, have you guys considered migrating to Nottingham's approach? We picked this approach because we didn't want to invent it ourselves and this happens to have a well defined RFC as well. If there's something Nottingham's proposal lacks of, I think we could provide some feedback and help making it better. We used json-home for Marconi v1 and we'd want the client to work in a 'follow your nose' way. Since, I'd prefer OpenStack modules to use the same language for this, I'm curious to know why - if so - you created your own spec, what are the benefits and if it's documented somewhere. Then why didn't Marconi follow the lead of one of the other projects? ;) LOOOL, I knew you were going to say that. I think I knew about you guys having something similar but at some point I most have forgotten about it. That being said, the main rationals were: 1) Using something documented and known upstream made more sense and it also helps getting more contributions from the community. 2) We already knew it, which falls back in point 1. I completely agree though - standardized version discovery across the ecosystem would be fantastic. All that being said, I don't think it would be very hard to migrate Marconi to something common if we agree that json-home is not good enough for OpenStack. Nonetheless, it'd be a shame not to provide feedback to Mark Nottingham about it. So far, his approach has been good enough for us - but, you know, Marconi is still way too small. Is keystone's home schema spec documented somewhere? Cheers, FF -- @flaper87 Flavio Percoco ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Keystone][Marconi][Oslo] Discoverable home document for APIs (Was: Re: [Nova][Glance] Support of v1 and v2 glance APIs in Nova)
On Tue, Nov 26, 2013 at 2:47 AM, Flavio Percoco fla...@redhat.com wrote: On 25/11/13 16:50 -0600, Dolph Mathews wrote: On Mon, Nov 25, 2013 at 2:41 AM, Flavio Percoco fla...@redhat.com wrote: On 25/11/13 09:28 +1000, Jamie Lennox wrote: So the way we have this in keystone at least is that querying GET / will return all available API versions and querying /v2.0 for example is a similar result with just the v2 endpoint. So you can hard pin a version by using the versioned URL. I spoke to somebody the other day about the discovery process in services. The long term goal should be that the service catalog contains unversioned endpoints and that all clients should do discovery. For keystone the review has been underway for a while now: https://review.openstack.org/#/c/38414/ the basics of this should be able to be moved into OSLO for other projects if required. Did you guys create your own 'home document' language? or did you base it on some existing format? Is it documented somewhere? IIRC, there's a thread where part of this was discussed, it was related to horizon. I'm curious to know what you guys did and if you knew about JSON-Home[0] when you started working on this. It looks like our multiple choice response might predate Nottingham's proposal, but not by much. In keystone, it's been stable since I joined the project, midway through the diablo cycle (summer 2011). I don't know any more history than that, but I've CC'd Jorge Williams, who probably knows. I really like Nottingham's approach of adding relational links from the base endpoint, I've been thinking about doing the same for keystone for quite a while. As crazy as it sounds, have you guys considered migrating to Nottingham's approach? It only sounds crazy because I have no idea how to migrate an unversioned endpoint :) Skimming through his proposal, it looks like it might actually be compatible with ours to include side by side? If so, we could support both for a couple releases before moving on. Does this proposal have much traction outside the OpenStack community? (and how much traction does it have within the community already?) We picked this approach because we didn't want to invent it ourselves and this happens to have a well defined RFC as well. If there's something Nottingham's proposal lacks of, I think we could provide some feedback and help making it better. We used json-home for Marconi v1 and we'd want the client to work in a 'follow your nose' way. Since, I'd prefer OpenStack modules to use the same language for this, I'm curious to know why - if so - you created your own spec, what are the benefits and if it's documented somewhere. Then why didn't Marconi follow the lead of one of the other projects? ;) LOOOL, I knew you were going to say that. I think I knew about you guys having something similar but at some point I most have forgotten about it. That being said, the main rationals were: 1) Using something documented and known upstream made more sense and it also helps getting more contributions from the community. 2) We already knew it, which falls back in point 1. Hey, you set yourself up! Seriously though, I welcome the innovation. I completely agree though - standardized version discovery across the ecosystem would be fantastic. All that being said, I don't think it would be very hard to migrate Marconi to something common if we agree that json-home is not good enough for OpenStack. Nonetheless, it'd be a shame not to provide feedback to Mark Nottingham about it. So far, his approach has been good enough for us - but, you know, Marconi is still way too small. Is keystone's home schema spec documented somewhere? It's actually documented as part of the v2.0 API for keystone, although I really believe it should be it's own API specification (e.g. Nottingham's approach): https://github.com/openstack/identity-api/blob/master/openstack-identity-api/v2.0/src/docbkx/wadl/identity-admin.wadl#L185 https://github.com/openstack/identity-api/blob/master/openstack-identity-api/v2.0/src/docbkx/xsd/version.xsd#L35 We use the same basic structure to serve the multiple choice response and versioned endpoints: GET / GET /v2.0/ GET /v3/ However, the multiple choice response contains the details for both versions. Cheers, FF -- @flaper87 Flavio Percoco ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev -- -Dolph ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
[openstack-dev] [Keystone][Marconi][Oslo] Discoverable home document for APIs (Was: Re: [Nova][Glance] Support of v1 and v2 glance APIs in Nova)
On 25/11/13 09:28 +1000, Jamie Lennox wrote: So the way we have this in keystone at least is that querying GET / will return all available API versions and querying /v2.0 for example is a similar result with just the v2 endpoint. So you can hard pin a version by using the versioned URL. I spoke to somebody the other day about the discovery process in services. The long term goal should be that the service catalog contains unversioned endpoints and that all clients should do discovery. For keystone the review has been underway for a while now: https://review.openstack.org/#/c/38414/ the basics of this should be able to be moved into OSLO for other projects if required. Did you guys create your own 'home document' language? or did you base it on some existing format? Is it documented somewhere? IIRC, there's a thread where part of this was discussed, it was related to horizon. I'm curious to know what you guys did and if you knew about JSON-Home[0] when you started working on this. We used json-home for Marconi v1 and we'd want the client to work in a 'follow your nose' way. Since, I'd prefer OpenStack modules to use the same language for this, I'm curious to know why - if so - you created your own spec, what are the benefits and if it's documented somewhere. Cheers, FF [0] http://tools.ietf.org/html/draft-nottingham-json-home-02 -- @flaper87 Flavio Percoco pgpSSZY2EwSLO.pgp Description: PGP signature ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Keystone][Marconi][Oslo] Discoverable home document for APIs (Was: Re: [Nova][Glance] Support of v1 and v2 glance APIs in Nova)
To most of your questions i don't know the answer as the format was in place
before i started with the project. I know that it is similar (though not
exactly the same) as nova's but not where they are documented (as they are
version independent)
I can tell you it looks like:
{
versions: {
values: [
{
status: stable,
updated: 2013-03-06T00:00:00Z,
media-types: [
{
base: application\/json,
type: application\/vnd.openstack.identity-v3+json
},
{
base: application\/xml,
type: application\/vnd.openstack.identity-v3+xml
}
],
id: v3.0,
links: [
{
href: http:\/\/localhost:5000\/v3\/,
rel: self
}
]
},
{
status: stable,
updated: 2013-03-06T00:00:00Z,
media-types: [
{
base: application\/json,
type: application\/vnd.openstack.identity-v2.0+json
},
{
base: application\/xml,
type: application\/vnd.openstack.identity-v2.0+xml
}
],
id: v2.0,
links: [
{
href: http:\/\/localhost:5000\/v2.0\/,
rel: self
},
{
href:
http:\/\/docs.openstack.org\/api\/openstack-identity-service\/2.0\/content\/,
type: text\/html,
rel: describedby
},
{
href:
http:\/\/docs.openstack.org\/api\/openstack-identity-service\/2.0\/identity-dev-guide-2.0.pdf,
type: application\/pdf,
rel: describedby
}
]
}
]
}
}
- Original Message -
From: Flavio Percoco fla...@redhat.com
To: OpenStack Development Mailing List (not for usage questions)
openstack-dev@lists.openstack.org
Sent: Monday, 25 November, 2013 6:41:42 PM
Subject: [openstack-dev] [Keystone][Marconi][Oslo] Discoverable home document
for APIs (Was: Re: [Nova][Glance]
Support of v1 and v2 glance APIs in Nova)
On 25/11/13 09:28 +1000, Jamie Lennox wrote:
So the way we have this in keystone at least is that querying GET / will
return all available API versions and querying /v2.0 for example is a
similar result with just the v2 endpoint. So you can hard pin a version
by using the versioned URL.
I spoke to somebody the other day about the discovery process in
services. The long term goal should be that the service catalog contains
unversioned endpoints and that all clients should do discovery. For
keystone the review has been underway for a while now:
https://review.openstack.org/#/c/38414/ the basics of this should be
able to be moved into OSLO for other projects if required.
Did you guys create your own 'home document' language? or did you base
it on some existing format? Is it documented somewhere? IIRC, there's
a thread where part of this was discussed, it was related to horizon.
I'm curious to know what you guys did and if you knew about
JSON-Home[0] when you started working on this.
We used json-home for Marconi v1 and we'd want the client to work in a
'follow your nose' way. Since, I'd prefer OpenStack modules to use the
same language for this, I'm curious to know why - if so - you
created your own spec, what are the benefits and if it's documented
somewhere.
Cheers,
FF
[0] http://tools.ietf.org/html/draft-nottingham-json-home-02
--
@flaper87
Flavio Percoco
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Keystone][Marconi][Oslo] Discoverable home document for APIs (Was: Re: [Nova][Glance] Support of v1 and v2 glance APIs in Nova)
On Mon, Nov 25, 2013 at 2:41 AM, Flavio Percoco fla...@redhat.com wrote: On 25/11/13 09:28 +1000, Jamie Lennox wrote: So the way we have this in keystone at least is that querying GET / will return all available API versions and querying /v2.0 for example is a similar result with just the v2 endpoint. So you can hard pin a version by using the versioned URL. I spoke to somebody the other day about the discovery process in services. The long term goal should be that the service catalog contains unversioned endpoints and that all clients should do discovery. For keystone the review has been underway for a while now: https://review.openstack.org/#/c/38414/ the basics of this should be able to be moved into OSLO for other projects if required. Did you guys create your own 'home document' language? or did you base it on some existing format? Is it documented somewhere? IIRC, there's a thread where part of this was discussed, it was related to horizon. I'm curious to know what you guys did and if you knew about JSON-Home[0] when you started working on this. It looks like our multiple choice response might predate Nottingham's proposal, but not by much. In keystone, it's been stable since I joined the project, midway through the diablo cycle (summer 2011). I don't know any more history than that, but I've CC'd Jorge Williams, who probably knows. I really like Nottingham's approach of adding relational links from the base endpoint, I've been thinking about doing the same for keystone for quite a while. We used json-home for Marconi v1 and we'd want the client to work in a 'follow your nose' way. Since, I'd prefer OpenStack modules to use the same language for this, I'm curious to know why - if so - you created your own spec, what are the benefits and if it's documented somewhere. Then why didn't Marconi follow the lead of one of the other projects? ;) I completely agree though - standardized version discovery across the ecosystem would be fantastic. Cheers, FF [0] http://tools.ietf.org/html/draft-nottingham-json-home-02 -- @flaper87 Flavio Percoco ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev -- -Dolph ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
