On 12/07/2012 07:24 AM, Jiří Stránský wrote:
[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. (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 a!
s!
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.
To brainstorm further - if we make it a separate resource, I wonder
if we should make it totally separate, like Tim has it (template can
be created independently of images). Say:
/api/deployabletemplates/:id
Then deployables and deployments DB records would link to these
templates, and templates would have to become read-only (create, but
never update), like in Tim.
This would force us to do significant changes in the DB model as well
(and I wonder if we'd want/need to change UI workflow anyhow),
because currently the template is embedded as an attribute into
deployable and deployment. This solution would be probably very time
consuming to implement, but should be possible.
Or, if we should make it as a simple nested subresource. Say:
/api/deployables/:deployable_id/template
/api/deployment/:deployment_id/template
This approaich is imho possible without performing a major surgery on
Conductor and solves the problem of API representation. The first
approach on the other hand seems a bit cleaner by design.
I cannot decide right now which one I'd prefer more :)
This thread got somehow forgotten :) Mainn actually just pinged me
about Conductor + Winged Monkey and we found out that we need to have
this decided.
1) Deployable XMLs
So do you guys think it is desirable to model deployable XMLs like this:
<deployment id='1' href='.../api/deployments/1'>
<deployable_template href=".../api/deployments/1/deployable_template"/>
</deployment>
or should we embed them into <deployment> as <deployable_xml>?
^^ This issue touches also instances API and deployables API. I don't
have a sharp opinion here, but I'd like to make sure that we come up
with something consistent in our pull requests and not different
solutions per author :)
After you described how a separate resource would work, I'm tempted to
go with the simpler option and have the them embedded. A separate
resource is better than cdata, but I'm having trouble seeing how it
would be better than embedding them.
With deployables, embedding presents a problem in that we call the name
of the resource deployable and the actual template/xml is also called
deployable. This will hopefully resolve itself with the future renaming
effort. And it is probably not a deal breaker as long as it is still
valid xml.
2) States
Can I assume that printing state of deployments/deployables this way
is correct?
<deployment>
<state>running</state>
</deployment>
Right now I don't need decision about starting/stopping instances,
just want to assert that this is the way we'll be printing states. I'd
like to have deployment GET ready for Mainn this sprint with all info
he needs.
Martyn, did you guys discuss states any further in the last tech cabal
meeting?
As for printing, I'm ok with that.
Thanks :)
J.
