[openstack-dev] [keystone] endpoint versioning in API v3

Jay Pipes jaypipes at gmail.com
Tue Jan 29 15:37:00 UTC 2013


On 01/28/2013 03:21 PM, Dolph Mathews wrote:
> I just noticed that we overlooked/forgot a feature from the v2
> serviceCatalog API which includes the following attributes on each endpoint:
> 
>   "versionId": "1.0",
>   "versionList": "https://compute.north.host/",
>   "versionInfo": "https://compute.north.host/v1.0/",
> 
> I never completely understood the intended use case for these
> attributes... e.g. if you can ask the remote service for a 'version
> list' then why does keystone need to redundantly identify the API
> version of the endpoint and enumerate options for each API version? I
> don't think you should have to revise your service catalog to roll out a
> new API version, either. IMO, clients should (ideally) start with an
> unversioned endpoint, receive a 300 Multiple Choice response, and select
> a compatible/acceptable versioned endpoint before proceeding.
> 
> Is anyone using this feature in v2 and want to see it carried forward to v3?

I think versionList is pointless, as you mention above the proper way of
handling this is a 300 Multiple Choice response on the base endpoint.
The endpoints themselves should be the source of truth about what
versions of an API they expose or support. Keystone, IMHO, should merely
be a directory of endpoints/services, not a directory of endpoints and
API versions on an endpoint.

So, I'd prefer very much to see Keystone just return, for example:

GET /services
[
{
  "type": "openstack.compute",
  "region": "north",
  "uri": "https://compute.north.host.com"
},
{
  "type": "openstack.image",
  "region": "north",
  "uri": "https://image.north.host.com"
},
{
  "type": "openstack.volume",
  "region": "north",
  "uri": "https://volume.north.host.com"
},
{
  "type": "ec2.compute",
  "region": "north",
  "uri": "https://ec2.north.host.com"
}
]

and then have the requesting client query and cache the result of a call
to the service endpoint's base URI, which would return the 300 Multiple
Choice with a version information dictionary particular to that endpoint.

That way you keep the source of truth about the endpoint's exposed API
versions where it belongs: in the endpoint that publishes the API.

Also, I re-iterate it would be awesome to be able to do the following in
Keystone:

GET https://auth.host.com/regions
[
{
  "name": "north",
  "uri": "https://auth.north.host.com"
}.
{
  "name": "south",
  "uri": "https://auth.south.host.com"
}
]

as well as:

GET https://auth.host.com/availability-zones
[
{
  "region": "north",
  "name": "zone1",
  "uri": "https://auth.zone1.north.host.com"
}.
{
  "region": "north",
  "name": "zone2",
  "uri": "https://auth.zone2.north.host.com"
},
{
  "region": "south",
  "name": "zone1",
  "uri": "https://auth.zone1.south.host.com"
}.
{
  "region": "south",
  "name": "zone2",
  "uri": "https://auth.zone2.south.host.com"
}
]

With requests to a an individual region's Keystone service returning
only the availability zones in that region:

GET https://auth.north.host.com/availability-zones
[
{
  "region": "north",
  "name": "zone1",
  "uri": "https://auth.zone1.north.host.com"
}.
{
  "region": "north",
  "name": "zone2",
  "uri": "https://auth.zone2.north.host.com"
}
]

This way we would be able to structure deployments in a way that would
enable clients to find global information about the regions in a
deployment as well as finer-grained drill-down information about
endpoints in a specific region or availability zone by simply following
the URIs.

Best,
-jay



More information about the OpenStack-dev mailing list