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:22:20 UTC