On Sat, Jun 20, 2015 at 9:14 AM, Devananda van der Veen
Almost all of our discussions so far on this topic have left something out,
which Monty pointed out to me last week. I'm following up now because
What we're versioning here are API's, not packages. It's not a question of
numbering and dependency ordering, but of communicating support[ed|able]
interfaces between running services. Libtool is more relevant than semver.
Right now we lack a means to express that the API response is
"compatible-with" a particular previously-released version of the API. If we
had that, instead of "current-version", I believe we would have much happier
users (and a happier Dmitry and jroll).
Every HTTP response from Ironic today includes three headers: min, max, and
version. The service can present an older API version, as long as it is
greater-than-or-equal-to the minimum supported version, even if that version
is incompatible with the maximum supported version. It does this by
rewriting responses to match what was expected in the requested (older)
When the newer version is identical for all interfaces present in the
older version, this can be called compatible. Dmitry's point is that we
don't need to hide newer interfaces from users who request an older API
version, because the client won't know or care about things that weren't in
the version it requested.
However, we do need to signal their presence, and we don't have a good
means for that right now. We also need to signal to the client that the
response given is "compatible with" a certain "age" of API, even if it's not
exactly the same. And we don't have any means for that, either.
Time for an example....
Let's say that an incompatible change was made in v1.3. Let's also say that
a change was made in v1.5 that added a new endpoint. Today, this is what the
response headers would look like when calling a server running v1.5.
a) client requests v1.2, receives headers (min: 1.1, max: 1.5, current: 1.2)
b) client requests v1.4, receives headers (min: 1.1, max: 1.5, current 1.4)
c) client requests v1.5, receives headers (min: 1.1, max: 1.5, current: 1.5)
What we have implemented today is that in case (b), the service will hide
any changes that we introduced in v1.5. But those changes did not affect any
functionality of the v1.4 API, so Dmitry objects to this. So do I.
The issue at hand is the response in case (b) ... though after spending the
last several months working on api versioning, I actually think all of those
are poor responses.
What I believe we should have:
a) client requests v1.2, receives headers (min: 1.1, max: 1.5,
b) client requests v1.4, receives headers (min: 1.1, max: 1.5,
b) client requests v1.5, receives headers (min: 1.1, max: 1.5,