Open Stack

Please excuse me for being vague with many parts of this reply. Since I'm still learning the terminology used throughout this project, I chose to be non-specific rather than risk using the wrong name and distract from the points I'm trying to make.

>From a client perspective, the most important issue in writing a reliable application that is truly portable across implementations is ensuring that the API defines a way to determine whether or not a provider supports a particular optional feature. The precise manner in which that functionality is exposed does not matter so much. My only concern with consolidating feature discoverability into a single "endpoints" function, where users are expected to include standardized endpoints as well as non-standard endpoints ("extensions"), is the possibility of name collisions. In this case, it helps to reserve certain names for use with standardized features (e.g. names starting with OS- could be reserved for optional behavior defined in the OpenStack specifications, and names starting with {Vendor}- could be reserved for optional behavior defined elsewhere).

On the subject of "incrementing" an API version - this certainly makes sense for APIs that are linear. In practice, however, multiple implementations of similar features often produce aliased version numbers and/or overlapping version ranges, which makes incrementing the version number useless. This can be resolved by only using (and incrementing) API version numbers for the official, root-level specification. For a named extension, the "owner" of the extension acts as the root-level specification for the extension and should be the only one incrementing the version number. In cases where an API or extension has been altered from its original form, the alteration can be presented in a modular form, where the implementation supports the original versioned API under its originally published name and version, and offers the altered features as an extension with a new name. This allows the alterations to the core functionality to be linearly versioned independently from the core functionality itself.

Thank you,
Sam Harwell

-----Original Message-----
From: Jay Pipes [mailto:jaypipes at gmail.com] 
Sent: Tuesday, August 06, 2013 8:46 AM
To: openstack-dev at lists.openstack.org
Subject: Re: [openstack-dev] [Keystone] V3 Extensions Discoverability

On 08/06/2013 01:19 AM, Jamie Lennox wrote:
> Hi all,
>
> Partially in response to the trusts API review in keystoneclient 
> (https://review.openstack.org/#/c/39899/ ) and my work on keystone API 
> version discoverability (spell-check disagrees but I'm going to assume 
> that's a word - https://review.openstack.org/#/c/38414/ ) I was 
> thinking about how we should be able to know what/if an extension is 
> available. I even made a basic blueprint for how i think it should work:
> https://blueprints.launchpad.net/python-keystoneclient/+spec/keystoneclient-extensions and then realized that GET /extensions is only a V2 API.
>
> Is this intentional? I was starting to make a review to add it to 
> identity-api but is there the intention that extensions should show up 
> within the endpoint APIs? There is no reason it couldn't work that way 
> and DELETE would just fail.

I would hope that extensions would *not* show up in the endpoints API.

Frankly, I'm not a fan of API extensions at all. I think they are silly and just promote an inconsistent and fractured user experience. I would highly prefer to just have a single API, versioned, with documentation online and in a versions/ resource that indicates what was changed, added, and deleted in each version.

If some vendor wants to provide some special API resource that naturally belongs in a related API -- for instance, trusts in the OpenStack Identity API -- then the new resource should simply be added to the one and only Identity API, the version of the API incremented, and on we go.

API extensions are more hassle than anything else. Let us promote standards, not endless extensibility at the expense of usability.

Best,
-jay

_______________________________________________
OpenStack-dev mailing list
OpenStack-dev at lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev