On 06/08/2011 02:09 PM, David Lutterkort wrote:
On Tue, 2011-06-07 at 06:45 -0400, Martyn Taylor wrote:
> Providing a formal deffinition of the XML for an API, makes using the
> API, in particular creating and maintaining client applications that
> utilise the API much simpler, and far clearer for a developer.
I completely agree that we need better docs for (at least) the
Deltacloud API. I am highly doubtful though that a grammar for the XML
is the right answer here - for the nitty-gritty of what's in the XML,
going to deltacloudd's HTML interface does the job for the most part.
I find XSD plain unreadable, and even a RelaxNG grammar doesn't quite
pay back the effort you need to put into it for this sort of API.
Yeah, it's extremely ugly. In that it has some resemblance to SOAP and
WSDL. And its W3 spec is one of the most unintelligible ones that i've
ever read.
> There are an array of tools that provide class generation, and
> automatic marshalling and unmarshalling of objects,
'Class generation' is really an artifact of certain features of some
languages; in languages like Ruby or Python there isn't really a need
for ahead-of-time class generation. The Deltacloud Ruby client, for
example, 'unmarshals' XML into Ruby objects dynamically, for the most
part following simle rules about how XML constructs are turned into Ruby
constructs.
I think class generation can still be useful for dynamic languages:
* If you are providing input to an API rather than parse its output.
* Some details of parsing the XML and mapping it to native classes,
e.g. type information, and whether something is a scalar or a list which
happens to have only 1 element, is useful too.
* For CLIs, pre-runtime information is desirable if you want to
generate man pages e.g.
The other advantage is that as Martyn already mentioned is to support
less dynamic languages, of which Java is probably the most important
example.
> generated straight from a formally defined XML Document, for
ruby,
> this project looks to offer these functions:
>
https://github.com/rubyjedi/soap4r .
As far as I can tell, this is simply a SOAP (blech) library. And much
less popular than Savon.
> In my experience writing Java and Android clients, I have found that
> the time spent creating an XSD or other formal XML definition, repays
> 10 fold in development time, and also makes keeping clients up to date
> alot simpler.
How exactly has having XSD helped you there (not trolling, I am really
curious)
In the Python SDK for RHEV it did save me time as i didn't have to code
the classes by hand. I could have taken the "dynamic class" approach but
it would not have given me type information. It's a tradeoff.
Regards,
Geert