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

On Aug 26, 2009, at 22:24 , Marcin Hanclik wrote:
> In DOM there is hasFeature() method, e.g. explicitly used in the  
> DOM3Events.
> If we want to drop versioning then I assume we should also drop  
> hasFeature(), since it is the same problem.

That is not for this group to decide, but in for all practical  
purposes hasFeature() can be considered dropped since nobody uses it.  
It cannot be trusted, and is therefore entirely useless.

> As stated below by Anne new releases of the specification may break  
> backwards compatibility.

Anne made an implicit distinction between breaking backwards  
compatibility and breaking existing, deployed, non-contrived code. One  
can construct cases of the former, but the idea is that one can't find  
cases of the latter. It's an idealistic versus pragmatic approach — in  
practice XHR2 does not break compared to XHR (i.e. it breaks no real  
code), even though strictissimo sensu one can construct an artificial  
counter-example:

       function isLocal (url) {
           try {
               var xhr = new XMLHttpRequest();
               xhr.open("GET", url, false);
               xhr.send();
           }
           catch (e) {
               return false;
           }
           return true;
       }

But even then, cases such as XHR2 are extremely rare to start with. If  
the breakage were to be found to be real, we'd just change the name.

> If it is ok, then I assume we should allow the content to advertise  
> based what (which version of) specification it was developed.

That relies on the assumption that an author knows which version of a  
specification she's authoring against. Most authors only have a vague  
notion that a specification even exists, don't know where to find it,  
and certainly wouldn't know which version is required for what. Most  
people just copy, paste, and adapt from MDC or from a blog somewhere.

> Content developed against versionless specifications has little  
> chance to survive and be usable if the specification changes.

That's why we take great care not to a) 99% of the time, change  
nothing; and b) the rest of the time, only change what doesn't break  
real-world code.

> As you may know, versioning - as a generic issue - is currently  
> discussed in TAG and WHATWG, so we could first look at the arguments  
> there, since my belief is that they are similar to ours.

I'm always happy to follow TAG discussions and always welcome the  
TAG's input, but I certainly won't put this WG on hold waiting for a  
TAG decision on versioning. But that's okay because it's not exactly  
as if this was new territory and we had to invent an architecture. We  
have an existing piece of architecture for API versioning that's  
informed by past successes and failures in addressing this issue:  
nothing has been shown to work other than organic growth.

--
Robin Berjon
   robineko — setting new standards
   http://robineko.com/

Received on Thursday, 27 August 2009 08:48:34 UTC