Open Stack

On 02/20/2014 09:55 AM, Christopher Yeoh wrote:
> On Thu, 20 Feb 2014 08:22:57 -0500
> Sean Dague <sean at dague.net> wrote:
>>
>> We're also duplicating a lot of test and review energy in having 2 API
>> stacks. Even before v3 has come out of experimental it's consumed a
>> huge amount of review resource on both the Nova and Tempest sides to
>> get it to it's current state.
>>
>> So my feeling is that in order to get more energy and focus on the
>> API, we need some kind of game plan to get us to a single API
>> version, with a single data payload in L (or on the outside, M). If
>> the decision is v2 must be in both those releases (and possibly
>> beyond), then it seems like asking other hard questions.
>>
>> * why do a v3 at all? instead do we figure out a way to be able to
>> evolve v2 in a backwards compatible way.
> 
> So there's lots of changes (cleanups) made between v2 and v3 which are
> really not possible to do in a backwards compatible way. One example
> is that we're a lot stricter and consistent on input validation in v3
> than v2 which is better both from a user and server point of view.
> Another is that the tasks API would be a lot uglier and really look
> "bolted on" if we tried to do so. Also doing so doesn't actually reduce
> the test load as if we're still supporting the old 'look' of the api we
> still need to test for it separately to the new 'look' even if we don't
> bump the api major version. 
> 
> In terms of code sharing (and we've experimented a bit with this for
> v2/v3) I think in most cases ends up actually being easier having two
> quite completely separate trees because it ends up diverging so much
> that having if statements around everywhere to handle the different
> cases is actually a higher maintenance burden (much harder to read)
> than just knowing that you might have to make changes in two quite
> separate places. 
> 
>> * if we aren't doing a v3, can we deprecate XML in v2 in Icehouse so
>> that working around all that code isn't a velocity inhibitor in the
>> cleanups required in v2? Because some of the crazy hacks that exist to
>> make XML structures work for the json in v2 is kind of special.
> 
> So I don't think we can do that for similar reasons we can't just drop
> V2 after a couple of cycles. We should be encouraging people off, not
> forcing them off. 
> 
>> This big bang approach to API development may just have run it's
>> course, and no longer be a useful development model. Which is good to
>> find out. Would have been nice to find out earlier... but not all
>> lessons are easy or cheap. :)
> 
> So I think what the v3 gives us is much more consistent and clean
> API base to start from. It's a clean break from the past. But we have to
> be much more careful about any future API changes/enhancements than we
> traditionally have done in the past especially with any changes which
> affect the core. I think we've already significantly raised the quality
> bar in what we allow for both v2 and v3 in Icehouse compared to previous
> releases (those frustrated with trying to get API changes in will
> probably agree) but I'd like us to get even stricter about it in the
> future because getting it wrong in the API design has a MUCH higher
> long term impact than bugs in most other areas. Requiring an API spec
> upfront (and reviewing it) with a blueprint for any new API features
> should IMO be compulsory before a blueprint is approved. 
> 
> Also micro and extension versioning is not the magic bullet which will
> get us out of trouble in the future. Especially with the core changes.
> Because even though versioning allows us to make changes, for similar
> reasons to not being able to just drop V2 after a couple of cycles
> we'll still need to keep supporting (and testing) the old behaviour for
> a significant period of time (we have often quietly ignored
> this issue in the past).
> 
> Ultimately the only way to free ourselves from the maintenance of two
> API versions (and I'll claim this is rather misleading as it actually
> has more dimensions to it than this) is to convince users to move from
> the V2 API to the "new one". And it doesn't make much difference
> whether we call it V3 or V2.1 we still have very similar maintenance
> burdens if we want to make the sorts of API changes that we have done
> for V3.

I want to flip this a little bit around. As an API consumer for an
upstream service I actually get excited when they announce a new version
and give me some new nobs to play with. Often times I'll even email
providers asking for certain API interfaces get exposed.

I do think we need to actually start from the end goal and work
backwards. My assumption is that 1 API vs. with 1 Data Format in L/M is
our end goal. I think that there are huge technical debt costs with
anything else. Our current course and speed makes us have 3 APIs/Formats
in that time frame.

There is no easy way out of this, but I think that the current course
and speed inhibits us in a lot of ways, not least of which is the
ability to get more people active in this part of Nova to help out.

	-Sean

-- 
Sean Dague
Samsung Research America
sean at dague.net / sean.dague at samsung.com
http://dague.net

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 482 bytes
Desc: OpenPGP digital signature
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140220/0612e81d/attachment.pgp>