Open Stack

On Wed, Aug 7, 2013 at 7:58 AM, Sam Harwell <sam.harwell at 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: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-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 at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 

-Dolph
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20130807/fa822b80/attachment.html>