[aerogear-dev] REST-based API Versioning

Thu Aug 28 10:46:04 EDT 2014

On Thu, Aug 28, 2014 at 4:26 PM, Bruno Oliveira <bruno at abstractj.org> wrote:

> Answers inline (this is just my personal opinion)
>
> On 2014-08-28, Matthias Wessendorf wrote:
> > On Thu, Aug 28, 2014 at 4:03 PM, Bruno Oliveira <bruno at abstractj.org>
> wrote:
> >
> > > I think this is something to fix at our SDKs,
> >
> >
> > like releasing 1.0.x (Server and SDKs), where the versioning is in?
>
> For our releases tagged as 1.0.0, make it clear that UPS 1.0.0 IS
> required, also make it clear at our docs the reasons behind it.
>
> >
> > That's possible. And that way, we can say, why are you using 1.0.0, we
> > released 1.0.1 with (some sort of) fixes
>
> For further releases of UPS server like 1.0.x, make it clear at our
> documentation with something like "This release requires the SDKs 1.0.x
> or superior" and make it clear the reasons behind it.
>
> Is not a perfect solution but....trade-offs.
>
I would also prefer this approach

> >
> > -M
> >
> >
> > > 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
> > >>
> > >
> > >
> > > _______________________________________________
> > > 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/aerogear-dev/attachments/20140828/7f21fa84/attachment-0001.html 