So I realize in my thinking I have been heavily influenced by my
thought process of supporting an existing client, rather than writing
a new client against the current API.
I had previously advocated that we don't need to bump the version
number, if we introduce API changes that won't break existing
functionality. IE: Code already written won't break.
However this doesn't account for new clients written against those
newer features, trying to connect to an older server that supports the
same API version.
I now feel that we should increment the minor number if we introduce
new features but existing features don't change. e.g. 1.0 gets bumped
to 1.1 if we extend the API in a way that adds new functionality
without breaking the existing functionality.
If we do introduce changes that break existing functionality, we need
to bump the major number. e.g. 1.0 becomes 2.0.
Thus I now think the first version of the API should be 1.0 rather than 1.
Thoughts?
Thanks,
Brian
P.S. - My apologies for not considering this use case before.
Good Choice it seems to a sensible defato standard in versioning.
Jim
···
On 23 June 2012 00:59, Brian Gupta wrote:
> So I realize in my thinking I have been heavily influenced by my
> thought process of supporting an existing client, rather than writing
> a new client against the current API.
>
> I had previously advocated that we don't need to bump the version
> number, if we introduce API changes that won't break existing
> functionality. IE: Code already written won't break.
>
> However this doesn't account for new clients written against those
> newer features, trying to connect to an older server that supports the
> same API version.
>
> I now feel that we should increment the minor number if we introduce
> new features but existing features don't change. e.g. 1.0 gets bumped
> to 1.1 if we extend the API in a way that adds new functionality
> without breaking the existing functionality.
>
> If we do introduce changes that break existing functionality, we need
> to bump the major number. e.g. 1.0 becomes 2.0.
>
> Thus I now think the first version of the API should be 1.0 rather than 1.
>
> So I realize in my thinking I have been heavily influenced by my
> thought process of supporting an existing client, rather than writing
> a new client against the current API.
>
> I had previously advocated that we don't need to bump the version
> number, if we introduce API changes that won't break existing
> functionality. IE: Code already written won't break.
>
> However this doesn't account for new clients written against those
> newer features, trying to connect to an older server that supports the
> same API version.
>
> I now feel that we should increment the minor number if we introduce
> new features but existing features don't change. e.g. 1.0 gets bumped
> to 1.1 if we extend the API in a way that adds new functionality
> without breaking the existing functionality.
>
> If we do introduce changes that break existing functionality, we need
> to bump the major number. e.g. 1.0 becomes 2.0.
>
> Thus I now think the first version of the API should be 1.0 rather than 1.
>
> Thoughts?
>
I guess the 1.x controllers could inherit from the same 1.0 base
controller, and override when needed… so
+1
Ohad
···
On Sat, Jun 23, 2012 at 2:59 AM, Brian Gupta wrote:
Thanks,
Brian
P.S. - My apologies for not considering this use case before.
>
>
>
> So I realize in my thinking I have been heavily influenced by my
> thought process of supporting an existing client, rather than writing
> a new client against the current API.
>
> I had previously advocated that we don't need to bump the version
> number, if we introduce API changes that won't break existing
> functionality. IE: Code already written won't break.
>
> However this doesn't account for new clients written against those
> newer features, trying to connect to an older server that supports the
> same API version.
>
> I now feel that we should increment the minor number if we introduce
> new features but existing features don't change. e.g. 1.0 gets bumped
> to 1.1 if we extend the API in a way that adds new functionality
> without breaking the existing functionality.
>
> If we do introduce changes that break existing functionality, we need
> to bump the major number. e.g. 1.0 becomes 2.0.
>
> Thus I now think the first version of the API should be 1.0 rather
> than 1.
>
> Thoughts?
>
>
> I guess the 1.x controllers could inherit from the same 1.0 base
> controller, and override when needed… so
> +1
+1 for minor number of the API version - it's good for the client to
find out if the feature it requires is there.
-1 for separate controllers for 1.1 - If API v 1.1 supports everything
in 1.0, what's the point of offering 1.0 and 1.1 by the same server?
– Ivan
···
On 06/24/2012 01:55 PM, Ohad Levy wrote:
> On Sat, Jun 23, 2012 at 2:59 AM, Brian Gupta > wrote:
> Ohad
>
>
> Thanks,
> Brian
>
> P.S. - My apologies for not considering this use case before.
>
>
>
>
>
>
> So I realize in my thinking I have been heavily influenced by my
> thought process of supporting an existing client, rather than writing
> a new client against the current API.
>
> I had previously advocated that we don't need to bump the version
> number, if we introduce API changes that won't break existing
> functionality. IE: Code already written won't break.
>
> However this doesn't account for new clients written against those
> newer features, trying to connect to an older server that supports the
> same API version.
>
> I now feel that we should increment the minor number if we introduce
> new features but existing features don't change. e.g. 1.0 gets bumped
> to 1.1 if we extend the API in a way that adds new functionality
> without breaking the existing functionality.
>
> If we do introduce changes that break existing functionality, we need
> to bump the major number. e.g. 1.0 becomes 2.0.
>
> Thus I now think the first version of the API should be 1.0 rather than 1.
>
> Thoughts?
>
>
> I guess the 1.x controllers could inherit from the same 1.0 base controller,
> and override when needed… so
> +1
>
> +1 for minor number of the API version - it's good for the client to find
> out if the feature it requires is there.
>
> -1 for separate controllers for 1.1 - If API v 1.1 supports everything in
> 1.0, what's the point of offering 1.0 and 1.1 by the same server?
I think I agree, sine a 1.1 controller should support 1.0 clients.
Perhaps older majornum.x APIs can be proxied somehow.
···
On Tue, Jun 26, 2012 at 10:23 AM, Ivan Nečas wrote:
> On 06/24/2012 01:55 PM, Ohad Levy wrote:
> On Sat, Jun 23, 2012 at 2:59 AM, Brian Gupta > wrote:
– Ivan
Ohad
Thanks,
Brian
P.S. - My apologies for not considering this use case before.
