Conductor API versioning

Michal Fojtik mfojtik at redhat.com
Wed Apr 11 12:19:16 UTC 2012


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





More information about the aeolus-devel mailing list