Hi,
I'd like to change some stuff in the deployments API draft and I'd like some ACKs
and/or comments on the numbered issues below. I know this API already went around once in
a RFC and sort of passed, but I think we missed things in there and didn't decide
others. I'd like to get the implementation right so that we don't have to change
it later :) The current draft is on wiki, the rest of this mail refers to this draft [1].
1) <owner_id>
*I wouldn't show owner information at all for now.* In an ideal case, this would be a
proper link to a "user" resource, but we don't have API to access user
information now. I think there's not much point in showing just an ID. We can add the
<user> link when we have the "user" resource implemented.
2) <created_at>, <updated_at>
*I wouldn't add these (yet), too.* I think our APIs, both Conductor and Tim, don't
show created_at/updated_at information, even though it is available in the models. We
could use <updated_at> with PUT requests to avoid concurrency issues, but I'd
rather see that as a project-wide decision first, not just implement it for a few
resources. So I want to leave these out to keep the APIs consistent. If we decide we want
this information in APIs, we can add it across all relevant resources.
3) <global_uptime>5 minutes</global uptime>
*I'll implement a standard way to serialize duration information - from XML
Schema[2].* E.g. 5 minutes would serialize as "P5M". CIMI uses it as well.
4) <deployable-xml>
*Should we wrap the deployable template into CDATA or not?* The benefit is that the inner
XML will not be parsed by the client when parsing the API response, so an error in the
template XML can't break the whole API response. And it is semantically cleaner,
because the template XML won't be part of the API response XML tree, but will be
treated as data, which it is. (Think if we provided JSON API, then the template XML would
be treated as a data too and not converted into a corresponding JSON structure, I'd
say.) The drawback is that our deployable then can't have a CDATA in it, because CDATA
nesting is not allowed. For deployable templates, this might not be a problem right now,
but I wonder about the future. E.g. for image templates it would be a problem [3]. So
I'm sort of on the fence here, maybe a bit in favour of not wrapping it into CDATA.
(Btw Tim solves this by having image template as a separate resource, but I'm not sure
we should go this way for deployables as we!
ll.)
5) <history>
*I think this should be modelled as a separate resource/collection*, as the number of
events associated with a deployment can grow limitlessly over time. CIMI has this
separated too in a form of EventLog resource, though I didn't get the time to read
this in detail yet.
Take care,
J.
[1]
https://redmine.aeolusproject.org/redmine/projects/aeolus/wiki/Deployment...
[2]
http://www.w3.org/TR/xmlschema-2/#duration
[3]
https://github.com/aeolus-incubator/templates/blob/master/games/BrowserQu...