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).
I'd love to hear your opinion on this.
- maros
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
On Tue, Apr 10, 2012 at 02:41:18PM +0200, 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.
Is there a discussion going on about the API in general? I don't have a strong opinion on versioning, but I do have a strong opinion on *having* an API, which we really don't right now. I didn't see a planning page / email for that, but I've been known to miss things right under my nose.
-- Matt
On 04/11/2012 03:37 PM, Matt Wagner wrote:
On Tue, Apr 10, 2012 at 02:41:18PM +0200, 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.
Is there a discussion going on about the API in general? I don't have a strong opinion on versioning, but I do have a strong opinion on *having* an API, which we really don't right now. I didn't see a planning page / email for that, but I've been known to miss things right under my nose.
There is indeed an effort to create a complete and consistent API for Conductor. The goal is to have an API that lets you do anything the UI can do.
It seems to be split in to multiple wiki pages (page per feature):
https://www.aeolusproject.org/redmine/projects/aeolus/wiki/Conductor_Image_M... https://www.aeolusproject.org/redmine/projects/aeolus/wiki/V2_Conductor_API_... https://www.aeolusproject.org/redmine/projects/aeolus/wiki/V2_Conductor_API_...
-- Matt
aeolus-devel@lists.fedorahosted.org