Open Stack

On Mon, Mar 03, 2014 at 12:32:04PM -0500, Russell Bryant wrote:
> 5) Capitalization and Naming Consistency
> 
> Some of the changes in the v3 API included changes to capitalization and
> naming for improved consistency.  If we stick with v2 only, we will not
> be able to make any of these changes.  However, we believe that not
> breaking any existing clients and not having to maintain a second API is
> worth not making these changes, or supporting some indirection to
> achieve this for newer clients if we decide it is important.

While naming inconsistencies are not pretty, they are ultimately
merely style issues. My view from working on API design in other
projects like libvirt is that "cleaning up style issues" is never
an acceptable justification for API breakage that would affect
downstream consumers of an API. The top priority in a public API,
is doing what's best for users of the API, since the pain suffered
by users upon API breakage usually far outweighs the pain suffered
by the people maintaining the API.

So for me cleaning up style inconsistencies in v2 API is not a
point that's relevant in making a decision to do a v3 API. It
is merely a pleasant consequence if there are other compelling
reasons that make a v3 API unavoidable.

> 6) Response Code Consistency and Correctness
> 
> The v2 API has many places where the response code returned for a given
> operation is not strictly correct. For example a 200 is returned when a
> 202 would be more appropriate. Correcting these issues should be
> considered for improving the future use of the API, however there does
> not seem to be any support for considering this a critical problem right
> now. There are two approaches that can be taken to improve this in v2:
> 
> Just fix them. Right now, we return some codes that imply we have dealt
> with a request, when all we have done is queue it for processing (and
> vice versa). In the future, we may change the backend in such a way that
> a return code needs to change to continue to be accurate anyway. If we
> just assume that return codes may change to properly reflect the action
> that was taken, then we can correct existing errors and move on.
> Accept them as wrong but not critically so. With this approach, we can
> strive for correctness in the future without changing behavior of our
> existing APIs. Nobody seems to complain about them right now, so
> changing them seems to be little gain. If the client begins exposing a
> version header (which we need for other things) then we could
> alternately start returning accurate codes for those clients.
> 
> The key point here is that we see a way forward with this in the v2 API
> regardless of which path we choose.

My experiance with libvirt is that error code reporting changes for
APIs are something that's acceptable to do if you are adding detection
of new error scenarios. The key thing is to document what applications
can expect from error codes, so that even if new error codes are
introduced, applications will still at least detect the scenario as
an error, and not success.


> 10) Conclusion and Proposal
> 
> The v3 API effort has produced a lot of excellent work.  However, the
> majority opinion seems to be that we should avoid the cost of
> maintaining two APIs if at all possible.  We should apply what has been
> learned to the existing API where we can and focus on making v2
> something that we can continue to maintain for years to come.
> 
> We recognize and accept that it is a failure of Nova project leadership
> that we did not come to this conclusion much sooner.  We hope to have
> learned from the experience to help avoiding a situation like this
> happening again in the future.
> 
> Please provide your input on this proposal, even if it is just agreement
> with this as the way forward.

What is the suggested plan of action & timeframe if this proposal is
adopted ?  Is there a sense of urgency to resolving this ? eg to avoid
shipping v3 in Icehouse & thus avoid getting locked into supporting
it ?

If the latter would there be any value in keeping v3 code in the tree,
but adding a code patch that forceably disables it (with no config param
to turn it back on), such that we can wait until Atlanta to have a face-
to-face discussion on its fate before taking the ultimate step of deleting
all its code ?

Regards,
Daniel
-- 
|: http://berrange.com      -o-    http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org              -o-             http://virt-manager.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: http://entangle-photo.org       -o-       http://live.gnome.org/gtk-vnc :|