[rhq-metrics] REST Api Versioning

mike thompson mithomps at redhat.com
Fri Dec 19 17:42:08 UTC 2014


> On 19 Dec 2014, at 09:25, Thomas Segismont <tsegismo at redhat.com> wrote:
> 
> Le 17/12/2014 16:49, mike thompson a écrit :
>> 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
> 
> "it is time": that is debatable :)
> 
> We are in version 0.2.x. I' bet we'll come across new issues with the API, even if we don't expect them now.
> 
>> 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
>> 
> 
> This one is my favorite. But I'd rather put the version information in the 'Accept' header, which you'll always have to provide to curl, and so saves the extra keystrokes.
> 
> See how Github is doing it:
> https://developer.github.com/v3/media/#request-specific-version <https://developer.github.com/v3/media/#request-specific-version>

Heh, this is what Heiko suggested on Thursday’s meeting. So yes, this looks like the method we will be using. Allow content negotiation to handle versioning.

I moved some of this conversation into a GitHub issue so we have a  better record of ‘why’ we went with what.

Please feel free to add to this issue:
	https://github.com/rhq-project/rhq-metrics/issues/97 <https://github.com/rhq-project/rhq-metrics/issues/97>



> 
>> 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
>> 
> 
> _______________________________________________
> 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/20141219/6e9c4dfd/attachment.html>


More information about the rhq-devel mailing list