On 11/29/2012 08:33 AM, Jiří Stránský wrote:
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.
Good point, I think you're pointing out the fact that we do need to
implement the user resource. As a first pass perhaps we can make it read
only with basic information like name, email, but not password. We can
leave owner_id out for now until that resource has been 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.
I think we do need to include these fields in the APIs. Perhaps
modified_by should be added too for auditing purposes.
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.
Sounds good. We should point to such documentation so people know what
the annotations mean.
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.)
I would vote for a separate resource. There is xml embedded in the
instance resource too, and this sounds like the cleanest way around it.
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.
Initially I wasn't sure if it needed to be modelled as a separate
resource. But that is looking like the right approach.