<div dir="ltr"><br><div class="gmail_extra"><div class="gmail_quote">On Wed, Aug 7, 2013 at 7:58 AM, Sam Harwell <span dir="ltr"><<a href="mailto:sam.harwell@rackspace.com" target="_blank">sam.harwell@rackspace.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">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.<br>
</blockquote><div><br></div><div>Fair enough! I'll attempt to "translate" a bit below as there's already some mixing of terminology in this thread.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
>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.</blockquote>
<div><br></div><div>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.</div>
<div><br></div><div>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).</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">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).<br>
</blockquote><div><br></div><div>That's exactly the convention that we follow, which I think alleviates your concern for name collisions above.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
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.<br>
<br>
Thank you,<br>
Sam Harwell<br>
<div class="HOEnZb"><div class="h5"><br>
-----Original Message-----<br>
From: Jay Pipes [mailto:<a href="mailto:jaypipes@gmail.com">jaypipes@gmail.com</a>]<br>
Sent: Tuesday, August 06, 2013 8:46 AM<br>
To: <a href="mailto:openstack-dev@lists.openstack.org">openstack-dev@lists.openstack.org</a><br>
Subject: Re: [openstack-dev] [Keystone] V3 Extensions Discoverability<br>
<br>
On 08/06/2013 01:19 AM, Jamie Lennox wrote:<br>
> Hi all,<br>
><br>
> Partially in response to the trusts API review in keystoneclient<br>
> (<a href="https://review.openstack.org/#/c/39899/" target="_blank">https://review.openstack.org/#/c/39899/</a> ) and my work on keystone API<br>
> version discoverability (spell-check disagrees but I'm going to assume<br>
> that's a word - <a href="https://review.openstack.org/#/c/38414/" target="_blank">https://review.openstack.org/#/c/38414/</a> ) I was<br>
> thinking about how we should be able to know what/if an extension is<br>
> available. I even made a basic blueprint for how i think it should work:<br>
> <a href="https://blueprints.launchpad.net/python-keystoneclient/+spec/keystoneclient-extensions" target="_blank">https://blueprints.launchpad.net/python-keystoneclient/+spec/keystoneclient-extensions</a> and then realized that GET /extensions is only a V2 API.<br>
><br>
> Is this intentional? I was starting to make a review to add it to<br>
> identity-api but is there the intention that extensions should show up<br>
> within the endpoint APIs? There is no reason it couldn't work that way<br>
> and DELETE would just fail.<br>
<br>
I would hope that extensions would *not* show up in the endpoints API.<br>
<br>
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.<br>
<br>
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.<br>
<br>
API extensions are more hassle than anything else. Let us promote standards, not endless extensibility at the expense of usability.<br>
<br>
Best,<br>
-jay<br>
<br>
_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
<br>
_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</div></div></blockquote></div><br><br clear="all"><div><br></div>-- <br><div><br></div>-Dolph
</div></div>