RE: ISSUE-4 (api-versioning): API Versioning [APIs - General]

Marcin,

The general consensus of this thread is to have no versioning.

A voting process will be the most pragmatic route to concensus. As you
will know I raised my objection to versioning in BONDI on several
occasions. I don't remember much support for having versioning there
either, perhaps from 1 or 2 members. There was considered
counter-discussion for no versioning but it was still driven through and
made the specs. This was a mistake in my view, because:

- Versioning may work for proprietary solutions but not for a massively
distributed web. 
- Versioning is fundamentally not how the web works and is successful
(with rare exceptions, like HTTP, but look where that got us). 
- The web works on a cycle of iterative improvements to existing
technology and long may that continue.
- Specifications should be solid before publication i.e. tested in the
wild and the specs updated as required before publication. BONDI was a
quick process (and necessarily so) but W3C will take a longer term view
to publishing specifications.

This email thread will start to go round in circles as this discussion
has done many times before. I'd much prefer to just put it to the vote,
have clear acceptance criteria of any voting outcome and be done with
this issue early on.

Thanks,

Richard


> -----Original Message-----
> From: Marcin Hanclik [mailto:Marcin.Hanclik@access-company.com] 
> Sent: 27 August 2009 12:21
> To: Marcos Caceres
> Cc: public-device-apis@w3.org; Anne van Kesteren; Robin 
> Berjon; TIBBETT Richard RD-ILAB-LON
> Subject: RE: ISSUE-4 (api-versioning): API Versioning [APIs - General]
> 
> Hi Marcos,
> 
> In versioning the most important seems to be not the version 
> identifier of the specification document, but the version 
> identifier of the specification embedded in the content.
> It provides means for the potential implementation to 
> identify the content for potential incompatibilities.
> Otherwise we have at least 2 options:
> 1) content sniffing by the implementation
> 2) unnecessary code in the content to guess/sniff the 
> underlying implementation
> 
> >>Levels: build ontop, don't break backwards compatibility.
> 
> I am all for not breaking the backwards compatibility.
> As Anne stated earlier in the case of XHR the bc was broken 
> and handled implicitly.
> What then if we would really have to break backwards compatibility?
> Shall we give up the whole related ecosystem?
> Wouldn't it be better to state now - at start - that breaking 
> of the backwards compatibility is not intended, but MAY 
> happen, and we are prepared for it?
> 
> >>Sure. Is the above ok?
> Not really. I think about some technically detailed solution, 
> a kind of pattern for handling this issue.
> 
> >>Yikes! We got some work to do then! Hopefully, we can get those 
> >>numbers down to something more reasonable.
> I am not sure whether less entities will handled the planned 
> use cases.
> Also I do not know what number is meant as reasonable and 
> whether minimizing that number is our ultimate target.
> I may however think of the distribution of the entities, e.g. 
> more constants and less interfaces or so.
> This is then an API Design Pattern that we could elaborate on.
> 
> Thanks,
> Marcin
> 
> Marcin Hanclik
> ACCESS Systems Germany GmbH
> Tel: +49-208-8290-6452  |  Fax: +49-208-8290-6465
> Mobile: +49-163-8290-646
> E-Mail: marcin.hanclik@access-company.com
> 
> -----Original Message-----
> From: Marcos Caceres [mailto:marcosc@opera.com]
> Sent: Thursday, August 27, 2009 12:59 PM
> To: Marcin Hanclik
> Cc: public-device-apis@w3.org; Anne van Kesteren; Robin 
> Berjon; <richard.tibbett@orange-ftgroup.com>
> Subject: Re: ISSUE-4 (api-versioning): API Versioning [APIs - General]
> 
> 
> 
> Marcin Hanclik wrote:
> > Hi Marcos,
> >
> > I am ok with voting, this gives us some guidance for the future.
> >
> > The only issue is what we vote for and against?
> 
> Basically, versions at all levels, including Name of API: "Camera 1.0"
> VS no-versioning at any level.
> 
> Where versioning is "the process of assigning either unique 
> version names or unique version numbers to unique states of 
> [a specification and its APIs]. Within a given version number 
> category (major, minor), these numbers are generally assigned 
> in increasing order and correspond to new developments in the 
> [specification]. At a fine-grained level, revision control is 
> used for keeping track of incrementally different versions of 
> electronic information." (adapted from Wikipedia)
> 
> > If we vote against versioning, what is then the practical 
> alternative?
> 
> Levels: build ontop, don't break backwards compatibility. 
> Comparability in the future can be broken if a mass of data, 
> say a sample of 10,000,000 documents or deployments in terms 
> of marketshare, can be shown that prove that an specification 
> is being used in the wild in some undermentioned manner or 
> has been consistently implemented differently than what was 
> specified at a lower level (i.e., brokenness has become 
> de-facto, like is the case with HTML parsing VS SGML parsing).
> 
> Levels cannot be explicitly identified through versions. 
> Level is identified through supported capability.
> 
> > Could we then (clearly) identify what we vote for in that case?
> 
> Sure. Is the above ok?
> 
> > Some statistics:
> >
> > a)
> > XMLHttpRequest [1] defines 1 interface with 5 methods and 6 
> attributes.
> > Additionally [1] states what is left for future [2].
> >
> > b)
> > BONDI 1.01 [3] defines a bit more as summarized at [4]:
> > interfaces: 68,
> > attributes: 116,
> > constants: 82,
> > methods: 177,
> > typedefs: 24.
> 
> Yikes! We got some work to do then! Hopefully, we can get 
> those numbers down to something more reasonable.
> 
> > The above provides very rough information about the extent 
> of what we are heading for.
> > When starting the work in DAP I think we should prepare 
> ourselves to cope with that amount of Web IDL, accompanying 
> documentation, state machines etc.
> > Versioning may help and it is a kind of security policy, 
> just in case we would need to break backwards compatibility 
> due to some technical arguments coming late.
> 
> Yes, we know the issues. Lets not debate them again.
> 
> > I understand that each vendor wants to differ.
> > The issue is whether the outcome of DAP, i.e. the 
> documents/standards will be usable for a potential 
> user/developer and how they are going to evolve process-wise.
> 
> Exactly.
> 
> 
> 
> ________________________________________
> 
> Access Systems Germany GmbH
> Essener Strasse 5  |  D-46047 Oberhausen HRB 13548 
> Amtsgericht Duisburg
> Geschaeftsfuehrer: Michel Piquemal, Tomonori Watanabe, Yusuke Kanda
> 
> www.access-company.com
> 
> CONFIDENTIALITY NOTICE
> This e-mail and any attachments hereto may contain 
> information that is privileged or confidential, and is 
> intended for use only by the individual or entity to which it 
> is addressed. Any disclosure, copying or distribution of the 
> information by anyone else is strictly prohibited.
> If you have received this document in error, please notify us 
> promptly by responding to this e-mail. Thank you.
>

Received on Thursday, 27 August 2009 11:48:35 UTC