[rhq-metrics] REST Api Versioning

Thomas Segismont tsegismo at redhat.com
Fri Dec 19 17:25:29 UTC 2014


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

> 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
>



More information about the rhq-devel mailing list