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.

Received on Thursday, 27 August 2009 10:59:22 UTC