[rhq-metrics] REST Api Versioning

mike thompson mithomps at redhat.com
Wed Dec 17 20:29:20 UTC 2014


> On 17 Dec 2014, at 11:24, John Sanda <jsanda at redhat.com> wrote:
> 
>> 
>> On Dec 17, 2014, at 10:49 AM, mike thompson <mithomps at redhat.com <mailto:mithomps at redhat.com>> wrote:
>> 
>> 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.
> 
> Can you elaborate on URIs changing over time? Not quite sure I understand.
Sure, somewhere in the client config for REST Uris there would be:
	/rhq-metrics/v1.0/...
When we move to version 1.1 it would change to 
	/rhq-metrics/v1.1/…

Depending on the scripts and how they are setup this might break existing clients (or possibly worse, the client is unwittingly stuck on v1.0 as we move on and add new Api versions.

> 
>> 
>> 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 <mailto:rhq-devel at lists.fedorahosted.org>
>> https://lists.fedorahosted.org/mailman/listinfo/rhq-devel <https://lists.fedorahosted.org/mailman/listinfo/rhq-devel>
> 
> _______________________________________________
> rhq-devel mailing list
> rhq-devel at lists.fedorahosted.org <mailto:rhq-devel at lists.fedorahosted.org>
> https://lists.fedorahosted.org/mailman/listinfo/rhq-devel <https://lists.fedorahosted.org/mailman/listinfo/rhq-devel>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.fedorahosted.org/pipermail/rhq-devel/attachments/20141217/840e0286/attachment-0001.html>


More information about the rhq-devel mailing list