[rhq-metrics] REST Api Versioning

mike thompson mithomps at redhat.com
Wed Dec 17 15:49:12 UTC 2014


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?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.fedorahosted.org/pipermail/rhq-devel/attachments/20141217/eedbb35d/attachment.html>


More information about the rhq-devel mailing list