[rhq-metrics] REST Api Versioning

Stefan Negrea snegrea at redhat.com
Thu Dec 18 15:35:32 UTC 2014


Hello,

The last link from stackoverflow is excellent (http://stackoverflow.com/a/398564). I am in favor of #2 for the simple reason that we will need to keep a few versions up and running side by side for backwards compatibility. I am sure we will not be able to keep v1 running along side v8 but we could have consecutive releases (eg. v2, v2.1, and v2.2) running at once. If we are to implement #1 or #3 right now, sooner or later we will have to also implement #2 in some capacity. 

And #2 takes care of backwards compatibility in the most elegant way possible. The code moves forward to a new version, and gets a new URL; while the old API stays behind accessible with an older, already established URL. This is a permanent solution for backwards compatibility with zero (or close to zero) code changes, and no code mangle.


Thank you,
Stefan 

----- Original Message -----
> From: "mike thompson" <mithomps at redhat.com>
> To: "rhq-devel" <rhq-devel at lists.fedorahosted.org>
> Sent: Wednesday, December 17, 2014 8:47:01 PM
> Subject: Re: [rhq-metrics] REST Api Versioning
> 
> 
> 
> 
> 
> On 17 Dec 2014, at 12:50, Heiko W.Rupp < hrupp at redhat.com > wrote:
> 
> As if InfoQ was reading this conversation :-)
> 
> http://www.infoq.com/articles/roy-fielding-on-versioning
> 
> Not relevant to any previous info/decisions, but rather to further educate
> https://stackoverflow.com/questions/389169/best-practices-for-api-versioning
> and make a decision based on opinion.
> 
> 
> 
> 
> 
> 
> 
> 
> 
> Am 17.12.2014 um 21:27 schrieb Heiko W.Rupp < hrupp at redhat.com >:
> 
> +10 on #1
> 
> 
> 
> Am 17.12.2014 um 16:49 schrieb mike thompson < mithomps at redhat.com >:
> 
> As we get closer to getting more solid Uris for the REST Api it is time to
> discuss versioning for non-breaking changes to the REST Api. There are 3
> ways (maybe more) to version a REST Api:
> 
> 1) Http Header: header property “x-rhq-metrics-version”: “1.0”
> 
> 2) Uri: /rhq-metrics/v1.0/
> 
> 3) Query Param: /rhq-metrics/?version=1.0
> 
> 
> Approach # 1 is the most difficult to use for clients (setting via curl is a
> lot of extra keystrokes) but technically fits well with the Http REST usage
> model the best (that is what the header is for). However, instead of sending
> the version in the header each time we could default to current version if
> not present. This way, the default method is easy to use, but past versions
> can be customised via the header. Since, the current version will be used
> most of the time
> 
> Approach #2 seems the most straight forward (and popular) because the version
> is easily seen in the Uri. Although it has the disadvantage that Uris change
> over time. Because of this I would suggest that we not use this approach.
> 
> Approach #3 the query param approach is the least appealing from a pure REST
> architecture perspective as the query params are arguments to the individual
> method (by which the request probably already has been routed to version of
> the code. This means that we would need a global interceptor (or something)
> that first checks the params to see if the version param exists just to know
> what codebase version to use. Also, what if a method actually wants to use
> the ‘version’ parameter for its functionality (it can’t)?
> 
> 
> Given the fact, that most of the time the version we use is the current
> version, and only on occasion would we want to change the version to a past
> version then — Method #1 is my pick.
> 
> 
> 
> WDYT?
> _______________________________________________
> rhq-devel mailing list
> rhq-devel at lists.fedorahosted.org
> https://lists.fedorahosted.org/mailman/listinfo/rhq-devel
> 
> --
> Reg. Adresse: Red Hat GmbH, Technopark II, Haus C,
> Werner-von-Siemens-Ring 14, D-85630 Grasbrunn
> Handelsregister: Amtsgericht München HRB 153243
> Geschäftsführer: Charles Cachera, Michael Cunningham, Paul Hickey, Charlie
> Peters
> 
> _______________________________________________
> rhq-devel mailing list
> rhq-devel at lists.fedorahosted.org
> https://lists.fedorahosted.org/mailman/listinfo/rhq-devel
> 
> --
> Reg. Adresse: Red Hat GmbH, Technopark II, Haus C,
> Werner-von-Siemens-Ring 14, D-85630 Grasbrunn
> Handelsregister: Amtsgericht München HRB 153243
> Geschäftsführer: Charles Cachera, Michael Cunningham, Paul Hickey, Charlie
> Peters
> 
> _______________________________________________
> rhq-devel mailing list
> rhq-devel at lists.fedorahosted.org
> https://lists.fedorahosted.org/mailman/listinfo/rhq-devel
> 
> 
> _______________________________________________
> rhq-devel mailing list
> rhq-devel at lists.fedorahosted.org
> https://lists.fedorahosted.org/mailman/listinfo/rhq-devel
> 


More information about the rhq-devel mailing list