API RFC: Information in deployable #show

Jiří Stránský jstransk at redhat.com
Wed Dec 12 15:10:34 UTC 2012


[snip]

>> Yes this would be possible. However, there's also a question of how to show relationship semantics. For the first time I think, we hit the issue in API that the name of the attribute is different from the resource name. The attribute in question is not called "user", it is called "owner". I'd kinda like to indicate this somehow in the response for two reasons:
>>
>> * Simply to make clear what the relationship means. It's the same reason why our data model has the relationship named "owner", not "user". I believe this information shouldn't get lost.
>>
>> * In case there are multiple users linked to a deployment (or sth else) in the future, we'd *have* to indicate semantics to avoid ambiguity of having two <user> links.
>>
>> Maybe this could be indicated by <user rel="owner" ... />. I'm not sure of this and it's not a priority question right now, but imho it's a reason for not putting the <user> there at all for now.
> The other question here is really about whether the owner/user should be exposed in the API ever.  Do users need to know this information or is it simply an implementation detail.
>
> Is there any value in showing the user who owns an image?  What can they do with this information?  When we are writing the API we should not blindly copy the database models.  We need think about what makes sense.

Good point. I'm leaving <user> out for now.

[snip]
>>>>>> 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.
> This CDATA concept is very strange to me.  The original reason for us using CDATA was because of the initial crappy implementation we had in the images API.  Template is a resource just like any other. We should parse it and validate it like any other.
>
>>>>>> (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 !
> CDATA is only relevant when we are using an XML parser.  Having this attribute in JSON means nothing.  Tim treats Templates just like any other resource.  We do not need to tell the parser to ignore it's content.

Hmm that's interesting. So if/when Tim wants to provide JSON API, it would accept the template not as string with XML in it, but as fully structured JSON? And then convert the JSON into a corresponding XML representation before saving it to the database? (Because templates are saved in the DB as XML strings [1]...)

So far I thought of templates as "always XML by definition", and I thought they would be better treated as simple strings on the APIs. I'm not keen on the idea that if/when we decide to make JSON APIs, we'll also have to invent JSON variant of TDL for images, deployables, ...

[1] https://github.com/aeolus-incubator/tim/blob/master/app/models/tim/template.rb#L10

[snip]
>>
>> Unless I missed something important, I'm tempted to go the way of simple embedding without CDATA, as Richard suggested.
>>
>>
> +1

Ok, so I think we can pronounce this a consensus :) Thanks everyone.

J.


More information about the aeolus-devel mailing list