On Apr 10, 2012, at 2:41 PM, Maros Zatko wrote:
Good news everyone!
we held a meeting, and besides other things we've been discussing API and it's
versions too.
We haven't decided if we're going to support versioned API in the sense that
the client could make a choice what version of API is going to be used in communication
with Conductor.
My opinion is that we should not support versioned API, but we should include Conductor
version (and/or API version as well) in API entrypoint at least, so that the client would
know
to which version of API is talking to atm and all API breakage would be documented.
This might prevent some really old clients talking to Conductor but in general my thought
was
that we will support whole stack of components (including clients) as a bundle of some
version,
and when you update, everything would change at once so that there will be new client
version
in case of API breakage. I don't think that API will change that much with Conductor
versions (changes in routes can be managed by HATEOAS).
The good practice is to include the version of API in response HTTP headers:
Something like: Server: Conductor API/1.0.0
This header should be set for all responses.
I think we forget about one thing, which is kinda important. The links in HATEOAS model
should be 'absolute', because then the resulting media type can indicate to the
'blind'
client what address he should query to get the same response.
Just my .50cents.
-- Michal