Support for API Versioning and Service Type in Service Catalog

Registered by Ziad Sawalha

Current response to the Authenticate call returns a service catalog that does not inherently support multiple versions of catalog endpoints. THe problem with that is that as endpoint versions change, the catalog will also need to change. This could be problematic for client code that was writing expecting a specific version. That version should be supported in the catalog for as long as it is supported at that endpoint. This would mean we would have multiple endpoints listed - one for each version.

A better solution would be to categorize services by version as well so the XML path or JSON hierarchy does not change for the duration that that specific version is supported at that endpoint.

The current service catalog also does not help determine types. Since the naming could be inconsistent, a type is needed so we know if we are looking at a compute, object storage, or other kind of service.

Sample catalog with versioning and servicetype (aka endpoint type):

XML:
<?xml version="1.0" encoding="UTF-8"?>
<auth xmlns="http://docs.openstack.org/identity/api/v2.0">
    <token expires="2010-11-01T03:32:15-05:00"
        id="ab48a9efdfedb23ty3494"/>
    <serviceCatalog>
        <service type="compute" name="Nova Cloud Servers">
            <endpoint
                region="DFW"
                publicURL="https://dfw.servers.api.rackspacecloud.com/v1.1/blah-blah"
                internalURL="https://ord.snet-servers.api.rackspacecloud.com/v1.1/blah-blah">
                <version
                    id="1.1"
                    info="https://dfw.servers.api.rackspacecloud.com/v1.1"
                    list="https://dfw.servers.api.rackspacecloud.com/"/>
             </endpoint>
            <endpoint region="DFW"
                publicURL="https://dfw.servers.api.rackspacecloud.com/v1.0/blah-blah"
                internalURL="https://dfw.snet-servers.api.rackspacecloud.com/v1.0/blah-blah">
                <version
                    id="1.0"
                    info="https://dfw.servers.api.rackspacecloud.com/v1.0"
                    list="https://dfw.servers.api.rackspacecloud.com/"/>
            </endpoint>
           <endpoint
                region="ORD"
                publicURL="https://ord.servers.api.rackspacecloud.com/v1.1/blah-blah"
                internalURL="https://ord.snet-servers.api.rackspacecloud.com/v1.1/blah-blah">
                <version
                    id="1.1"
                    info="https://ord.servers.api.rackspacecloud.com/v1.1"
                    list="https://ord.servers.api.rackspacecloud.com/"/>
                </endpoint>
         </service>
         <service type="compute" name="Legacy Cloud Servers"
             <endpoint
                 version="1.0"
                 publicURL="https://servers.api.rackspacecloud.com/v1.0/blah-blah"/>
             <endpoint
                 version="1.1"
                 publicURL="https://servers.api.rackspacecloud.com/v1.1/blah-blah"/>
        </service>
        <service type="object store" name="Cloud Files">
            <endpoint
                region="DFW"
                publicURL="https://service2.public.com/v2.0/blah-blah"/>
                internalURL="https://service1.internal.com/v2.0/blahblah"/>
            <endpoint
                region="ORD"
                publicURL="https://service2.public.com/v2.0/blah-blah"/>
                internalURL="https://service1.internal.com/v2.0/blahblah"/>
        </service>
        <service name="Cloud DNS">
            <endpoint
                publicURL="https://service3.public.com/v2.0/blah-blah"/>
        </service>
    </serviceCatalog>
</auth>

JSON:
{
    "serviceCatalog": [{
        "name": "Cloud Servers"
        "type": "compute": [{
            "publicURL": "https://compute.north.host/v1/blah-blah",
            "internalURL": "https://compute.north.host/v1/blah-blah",
            "region": "North",
            "versionId": "1.0",
            "versionInfo": "uri",
            "versionList": "uri"
            }, {
            "publicURL": "https://compute.north.host/v1.1/blah-blah",
            "internalURL": "https://compute.north.host/v1.1/blah-blah",
            "region": "North",
            "versionId": "1.1",
            "versionInfo": "https://compute.north.host/v1.1/",
            "versionList": "https://compute.north.host/",
            }]
        },
        "name": "Cloud Files"
        "type": "object store": [{
            "publicURL": "https://compute.north.host/v1/blah-blah",
            "internalURL": "https://compute.north.host/v1/blah-blah",
            "region": "South",
            "versionId": "1.0",
            "versionInfo": "uri",
            "versionList": "uri"
            }, {
            "publicURL": "https://compute.north.host/v1.1/blah-blah",
            "internalURL": "https://compute.north.host/v1.1/blah-blah",
            "region": "South",
            "versionId": "1.1",
            "versionInfo": "https://compute.north.host/v1.1/",,
            "versionList": "https://compute.north.host/"
            },
            links: [{"rel": "next", "href": ": "uri}]
        },
        ,
        links: [{"rel": "next", "href": ": "uri}]
        ]
    }
}

Blueprint information

Status:
Complete
Approver:
Ziad Sawalha
Priority:
Undefined
Drafter:
Ziad Sawalha
Direction:
Approved
Assignee:
Yogeshwar
Definition:
Approved
Series goal:
Accepted for diablo
Implementation:
Implemented
Milestone target:
milestone icon diablo-4
Started by
Ziad Sawalha
Completed by
Ziad Sawalha

Related branches

Sprints

Whiteboard

Versioning could be part of URI or as a MIME Type just the way we have specified for keystone.Would all the openstack projects support both types of versioning schemes? Do we plan to support both type of calls or if all projects support MIME type versioning having URI devoid of version info could be enough.

Yogi

------------
Good question. I thought as a standard for all our services, we support URI as well as MIME type versioning. If we can confirm this, then we don't need to supply multiple versions of the endpoint in the catalog. My guess is that not all legacy services support this behavior. I think the initial proposal should support a combination of both. If the version is not specified, the user has to navigate to the appropriate versions via the url.

{
    "serviceCatalog": {
        "compute": [{
            "region": "North",
            [{
                "version": "1",
                "publicURL": "https://compute.north.host/v1/blah-blah"
            }, {
                "version": "2",
                "publicURL": "https://compute.north.host/v2/blah-blah"
                }]
        }],

      "swift": [{
            "region": "North",
             "publicURL": "https://compute.north.host/"
                }]
        }]
    }
}

Itari

(?)

Work Items

This blueprint contains Public information 
Everyone can see this information.