API RFC: Information in deployable #show

Richard Su rwsu at redhat.com
Fri Nov 30 00:18:36 UTC 2012


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.

>
> Take care,
>
> J.
>
>
> [1] 
> https://redmine.aeolusproject.org/redmine/projects/aeolus/wiki/Deployments#Show-a-deployments-details
> [2] http://www.w3.org/TR/xmlschema-2/#duration
> [3] 
> https://github.com/aeolus-incubator/templates/blob/master/games/BrowserQuest/fedora-16/browserquest_v1.2.2_f16.xml#L63-L65




More information about the aeolus-devel mailing list