[aerogear-dev] REST-based API Versioning

[Bruno Oliveira]

I think this is something to fix at our SDKs, and think about the legacy, that's the price to pay.


The easy solution is to defaults to 1.0.0, but it doesn't seem correct.
—
abstractj 
PGP: 0x84DC9914

On Thu, Aug 28, 2014 at 10:18 AM, Matthias Wessendorf <matzew at apache.org>
wrote:

> the problem is... our 1.0.0 SDKs do not specify a version :-)
> so, they would than talk to the latest greatest, that does not work.
> We need to have that in mind, when planing this.
> On Thu, Aug 28, 2014 at 2:39 PM, Lucas Holmquist <lholmqui at redhat.com>
> wrote:
>> +1 on Accept headers and also using the latest and greatest if no version
>> is specified/
>>
>> i believe this is what github also does
>>
>> On Aug 28, 2014, at 4:36 AM, Bruno Oliveira <bruno at abstractj.org> wrote:
>>
>> On 2014-08-28, Matthias Wessendorf wrote:
>>
>> On Thu, Aug 28, 2014 at 10:14 AM, Sebastien Blanc <scm.blanc at gmail.com>
>> wrote:
>>
>>
>>
>>
>> On Thu, Aug 28, 2014 at 9:29 AM, Daniel Bevenius <
>> daniel.bevenius at gmail.com> wrote:
>>
>> If we go for the accept header and the consumer don't provide it, what
>>
>> do we do ? Return an error or use implicitly the latest version ?
>> Perhaps we can return the current version to not break any existing
>> clients. New clients will need to provide an explicit version.
>>
>> Why not but for how long do we return the "old" version by default ? (cf
>> my questions around deprecation)
>>
>>
>> yep - I am for that: looks like I forgot, and I think we had that on our
>> face2face: no version == 1.0.0 (old)
>>
>>
>> I vote for return the latest, instead of something old. And specify old
>> versions if you want to.
>>
>>
>> -M
>>
>>
>>
>>
>> On 28 August 2014 09:25, Sebastien Blanc <scm.blanc at gmail.com> wrote:
>>
>> Some questions :
>>
>> * If we go for the accept header and the consumer don't provide it, what
>> do we do ? Return an error or use implicitly the latest version ?
>> * What will be our deprecation policy ? Do we want keep maintaining all
>> the versions forever or let's say for 1.1 we still provide 1.0 and for 2.0
>> we drop 1.0 ?
>>
>> About the implementation :
>> * I like the suggested CDI solution, if possible.
>> * Erik also mentionned OSGI and I'm -9999^99 to introduce that techno
>>
>> Sebi
>> ps : I just read this blog post and it's really interesting :
>> http://apiux.com/2013/05/14/api-versioning/
>>
>>
>>
>> On Thu, Aug 28, 2014 at 8:07 AM, Daniel Bevenius <
>> daniel.bevenius at gmail.com> wrote:
>>
>> +1 For using the Accept header to specify the version in the media type.
>>
>>
>> On 28 August 2014 07:50, Matthias Wessendorf <matzew at apache.org> wrote:
>>
>> Hello,
>>
>> for the 1.1.x (master) we are potentially doing some changes on the
>> Sender-API (see [1]).
>>
>> However, for backwards compatibility we need to think about API
>> versioning.
>>
>> For REST APIs there are (IMO) two options:
>> * accept header
>> * URIs
>>
>> On our Face2Face meeting we briefly talked about this and I think the
>> "accept header" solution was the one that had most fans. I think QMX added
>> that it is better for migration. One thing we were not clear on (I think):
>> What are HATEOS defined semantics?
>>
>>
>> Besides the what (headers vs. URI), I think we should think about
>> possible implementations, to switch different versions.
>>
>> Not sure, but wouldn't it be possible to inject an annotated
>> SenderService into the RESTful endpoint, based on header values ?
>> We could have a default impl (version 1.0.0) and an alternate one,
>> that is injected if the accept header indicate API version 1.1
>>
>> Any thoughts ?
>>
>> -Matthias
>>
>>
>> [1]
>> http://lists.jboss.org/pipermail/aerogear-dev/2014-August/008881.html
>>
>> --
>> Matthias Wessendorf
>>
>> blog: http://matthiaswessendorf.wordpress.com/
>> sessions: http://www.slideshare.net/mwessendorf
>> twitter: http://twitter.com/mwessendorf
>>
>> _______________________________________________
>> aerogear-dev mailing list
>> aerogear-dev at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>>
>>
>>
>> _______________________________________________
>> aerogear-dev mailing list
>> aerogear-dev at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>>
>>
>>
>> _______________________________________________
>> aerogear-dev mailing list
>> aerogear-dev at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>>
>>
>>
>> _______________________________________________
>> aerogear-dev mailing list
>> aerogear-dev at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>>
>>
>>
>> _______________________________________________
>> aerogear-dev mailing list
>> aerogear-dev at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>>
>>
>>
>>
>> --
>> Matthias Wessendorf
>>
>> blog: http://matthiaswessendorf.wordpress.com/
>> sessions: http://www.slideshare.net/mwessendorf
>> twitter: http://twitter.com/mwessendorf
>>
>>
>> _______________________________________________
>> aerogear-dev mailing list
>> aerogear-dev at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>>
>>
>>
>> --
>>
>> abstractj
>> PGP: 0x84DC9914
>> _______________________________________________
>> aerogear-dev mailing list
>> aerogear-dev at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>>
>>
>>
>> _______________________________________________
>> aerogear-dev mailing list
>> aerogear-dev at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>>
> -- 
> Matthias Wessendorf
> blog: http://matthiaswessendorf.wordpress.com/
> sessions: http://www.slideshare.net/mwessendorf
> twitter: http://twitter.com/mwessendorf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/aerogear-dev/attachments/20140828/790c8c2f/attachment.html