On Wed, Aug 7, 2013 at 7:58 AM, Sam Harwell <sam.harw...@rackspace.com>wrote:
> 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. > Fair enough! I'll attempt to "translate" a bit below as there's already some mixing of terminology in this thread. > > 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. This seems to presume that an API extension must always present a discrete endpoint, which may not be the case. A simple API extension may only add an attribute to an existing API response, for example. Our existing `GET /v#/extensions` satisfies the use case for your "endpoints function," however. To avoid any possible confusion, this API resource shouldn't be confused with Identity API's `GET /v3/endpoints` which is specifically an API for managing raw service endpoints (it's worth stressing that /v3/endpoints has no knowledge of the API extensions presented by those services, nor should it). > 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). > That's exactly the convention that we follow, which I think alleviates your concern for name collisions above. > > 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:jaypi...@gmail.com] > Sent: Tuesday, August 06, 2013 8:46 AM > To: openstack-dev@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-extensionsand > 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@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