5:45 a.m.
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.
There are an array of tools that provide class generation, and automatic marshalling and
unmarshalling of objects, generated straight from a formally defined XML Document, for
ruby, this project looks to offer these functions: https://github.com/rubyjedi/soap4r .
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. For DC Client I ended up writing my
own:
https://github.com/mtaylor/deltacloud-tools/blob/master/DeltaCloudClient/...
But, I think it would be better as a whole to adopt this approach from the start. It
would not only benefit the creation of the CLI but also anyone else who needs to utilise
these APIs
Martyn
_______________________________________________
deltacloud-devel mailing list
deltacloud-devel(a)lists.fedorahosted.org
https://fedorahosted.org/mailman/listinfo/deltacloud-devel
8:56 a.m.
Hi Martyn,
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.
There are an array of tools that provide class generation, and
automatic marshalling and unmarshalling of objects, generated straight
from a formally defined XML Document, for ruby, this project looks to
offer these functions: https://github.com/rubyjedi/soap4r .
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. For DC Client I ended up writing my own:
https://github.com/mtaylor/deltacloud-tools/blob/master/DeltaCloudClient/...
But, I think it would be better as a whole to adopt this approach from
the start. It would not only benefit the creation of the CLI but also
anyone else who needs to utilise these APIs
It might be good to compare your approach to the one taken by the
rhevm-api project. Indeed, only today, Geert wrote up some nice info on
how to write client bindings for the API using our schema:
https://fedorahosted.org/pipermail/rhevm-api/2011-June/002358.html
https://fedorahosted.org/rhevm-api/wiki/ClientBindings
Cheers,
Mark.
9:35 a.m.
Hi Mark,
Thanks for this link, interesting.
So it seems that RHEV-M does already provide an XML Schema (XSD). Which is the approach I
was trying to promote for our APIs. Creating this could be part of the CLI effort?
Quote:
"The creation of the class hierarchy is tremendously more simple if an XMLSchema code
generator is avalailable for your language/platform. This is because the RHEV API
itself provides an XMLSchema file that defines all the objects. This file can be used with
a code generator to generate the classes automatically. The Python bindings use the
"PyXB" schema generator for example. "
Also, (whilst we're here) another opinion of mine is that choosing a REST API over
than say SOAP (given it's advantages) results in one issue, which is that there is no
standard way to formally define it, compared to say a WSDL, and in my experience I've
found provided documentation insufficient. So, I think it might also be worth a bit of
effort, trying to really pin down the API as much as possible and do a good job
documenting the APIs as much as possible, not just supplying examples.
Cheers
Martyn
----- Original Message -----
From: "Mark McLoughlin" <markmc(a)redhat.com>
To: "Martyn Taylor" <mtaylor(a)redhat.com>
Cc: gjansen(a)redhat.com, aeolus-devel(a)fedorahosted.org
Sent: Tuesday, 7 June, 2011 2:56:21 PM
Subject: Re: CLI - Formal XML Definition
Hi Martyn,
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.
There are an array of tools that provide class generation, and
automatic marshalling and unmarshalling of objects, generated straight
from a formally defined XML Document, for ruby, this project looks to
offer these functions: https://github.com/rubyjedi/soap4r .
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. For DC Client I ended up writing my own:
https://github.com/mtaylor/deltacloud-tools/blob/master/DeltaCloudClient/...
But, I think it would be better as a whole to adopt this approach from
the start. It would not only benefit the creation of the CLI but also
anyone else who needs to utilise these APIs
It might be good to compare your approach to the one taken by the
rhevm-api project. Indeed, only today, Geert wrote up some nice info on
how to write client bindings for the API using our schema:
https://fedorahosted.org/pipermail/rhevm-api/2011-June/002358.html
https://fedorahosted.org/rhevm-api/wiki/ClientBindings
Cheers,
Mark.
_______________________________________________
aeolus-devel mailing list
aeolus-devel(a)lists.fedorahosted.org
https://fedorahosted.org/mailman/listinfo/aeolus-devel
9:47 a.m.
Hi Martin, Mark,
On 06/07/2011 04:35 PM, Martyn Taylor wrote:
Hi Mark,
Thanks for this link, interesting.
So it seems that RHEV-M does already provide an XML Schema (XSD). Which is the approach
I was trying to promote for our APIs. Creating this could be part of the CLI effort?
Quote:
"The creation of the class hierarchy is tremendously more simple if an XMLSchema
code generator is avalailable for your language/platform. This is because the RHEV API
itself provides an XMLSchema file that defines all the objects. This file can be used with
a code generator to generate the classes automatically. The Python bindings use the
"PyXB" schema generator for example."
XMLSchema has certainly been very useful in the RHEVM API project. I
must say though that on the other side, XMLSchema has frustrated me
quite a bit when doing the RHEV-M Python SDK and CLI. There's a couple
of reasons:
* It's too rich. If you don't properly constrain yourself, it will be
difficult to use the XMLSchema to provide YAML and JSON bindings,
because those have a less rich data model (no distinction between
attributes/elements, order is relevant, etc).
* It doesn't give you all you need to fully automatically create a
CLI. There is still hand-crafted metadata necessary to indicate e.g.
which elements are allowed and/or required for POST vs PUT. XMLSchema
cannot represent multiple types with the same element, and therefore you
cannot use XMLSchema itself to express these requirements if they are
different between e.g POST and PUT, which is almost always the case
(e.g. an attribute required for creation but non-updatable afterwards).
You could use custom annotations which XMLSchema supports, but then i
ask myself what's the point of using XMLSchema at all.
* The fact that it doesn't have un-ordered collections is just silly.
In reality there's two options: either accept non-validating XML (which
is what rhevm-api does), or require all clients to be validating clients
using the schema. No human user will remember the way in which the
elements have to go.
In summary I think something better should be possible to describe types
in a RESTful API. Probably something bespoke for RESTful applications is
needed, and i would base it on the JSON data model. It should be simpler
than XMLSchema, and essentially answer these questions:
* An accurate description of each type.
* What constraints are present on each type when used as a request
entity with the 4 RESTful HTTP methods.
* For human consumption, textual descriptions on the semantics of each
attribute of a type.
Maybe there's some stuff out there, but i'm not aware.
Regards,
Geert
10:28 a.m.
Hi Geert,
Some interesting points.
I'm going to sound like an XSD fiend here but:
----- Original Message -----
From: "Geert Jansen" <gjansen(a)redhat.com>
To: "Martyn Taylor" <mtaylor(a)redhat.com>
Cc: "Mark McLoughlin" <markmc(a)redhat.com>, aeolus-devel(a)fedorahosted.org
Sent: Tuesday, 7 June, 2011 3:47:23 PM
Subject: Re: CLI - Formal XML Definition
Hi Martin, Mark,
On 06/07/2011 04:35 PM, Martyn Taylor wrote:
Hi Mark,
Thanks for this link, interesting.
So it seems that RHEV-M does already provide an XML Schema (XSD). Which is the approach
I was trying to promote for our APIs. Creating this could be part of the CLI effort?
Quote:
"The creation of the class hierarchy is tremendously more simple if an XMLSchema
code generator is avalailable for your language/platform. This is because the RHEV API
itself provides an XMLSchema file that defines all the objects. This file can be used with
a code generator to generate the classes automatically. The Python bindings use the
"PyXB" schema generator for example."
XMLSchema has certainly been very useful in the RHEVM API project. I
must say though that on the other side, XMLSchema has frustrated me
quite a bit when doing the RHEV-M Python SDK and CLI. There's a couple
of reasons:
* It's too rich. If you don't properly constrain yourself, it will be
difficult to use the XMLSchema to provide YAML and JSON bindings,
because those have a less rich data model (no distinction between
attributes/elements, order is relevant, etc).
Is it not a feature to have a rich data model? It seems YAML has taken a subset of XML
and implemented that. But anything you can define in YAML and JSON can be defined in XML
* It doesn't give you all you need to fully automatically create a
CLI. There is still hand-crafted metadata necessary to indicate e.g.
which elements are allowed and/or required for POST vs PUT. XMLSchema
cannot represent multiple types with the same element, and therefore you
cannot use XMLSchema itself to express these requirements if they are
different between e.g POST and PUT, which is almost always the case
(e.g. an attribute required for creation but non-updatable afterwards).
You could use custom annotations which XMLSchema supports, but then i
ask myself what's the point of using XMLSchema at all.
Yes, I agree an XML Schema does not do everything you need to define a RESTFul API. But
that is no downfall of an XSD, it is the fact that there is no formal way to define a
RESTFul API in any sense. An XSD works with SOAP because we have the notion of a formally
defined SOAP API in terms of a WSDL, but there is no equivilent for REST.
* The fact that it doesn't have un-ordered collections is just silly.
In reality there's two options: either accept non-validating XML (which
is what rhevm-api does), or require all clients to be validating clients
using the schema. No human user will remember the way in which the
elements have to go.
This expresses 0 or more elements to be present in any order in the in the given
collection. You can override this: e.g.
<xs:all>
<xs:element ref="name" minOccurs="1"/>
</xs:all>
In summary I think something better should be possible to describe types
in a RESTful API. Probably something bespoke for RESTful applications is
needed, and i would base it on the JSON data model. It should be simpler
than XMLSchema, and essentially answer these questions:
* An accurate description of each type.
* What constraints are present on each type when used as a request
entity with the 4 RESTful HTTP methods.
* For human consumption, textual descriptions on the semantics of each
attribute of a type.
I agree this would be great. But XML already does all this^ re: data model.
What we are really missing is a formal definition of an Restful API
Maybe there's some stuff out there, but i'm not aware.
Regards,
Geert
Thanks
Martyn
_______________________________________________
aeolus-devel mailing list
aeolus-devel(a)lists.fedorahosted.org
https://fedorahosted.org/mailman/listinfo/aeolus-devel
11:05 a.m.
On 06/07/2011 05:28 PM, Martyn Taylor wrote:
Some interesting points.
I'm going to sound like an XSD fiend here but:
No problem, i have no horse in this race.
Hi Martin, Mark,
On 06/07/2011 04:35 PM, Martyn Taylor wrote:
> Hi Mark,
>
> Thanks for this link, interesting.
>
> So it seems that RHEV-M does already provide an XML Schema (XSD). Which is the
approach I was trying to promote for our APIs. Creating this could be part of the CLI
effort?
>
> Quote:
> "The creation of the class hierarchy is tremendously more simple if an XMLSchema
code generator is avalailable for your language/platform. This is because the RHEV API
itself provides an XMLSchema file that defines all the objects. This file can be used with
a code generator to generate the classes automatically. The Python bindings use the
"PyXB" schema generator for example."
XMLSchema has certainly been very useful in the RHEVM API project. I
must say though that on the other side, XMLSchema has frustrated me
quite a bit when doing the RHEV-M Python SDK and CLI. There's a couple
of reasons:
* It's too rich. If you don't properly constrain yourself, it will be
difficult to use the XMLSchema to provide YAML and JSON bindings,
because those have a less rich data model (no distinction between
attributes/elements, order is relevant, etc).
Is it not a feature to have a rich data model? It seems YAML has taken a subset of XML
and implemented that. But anything you can define in YAML and JSON can be defined in XML
Correct, but it's the reverse that's the problem: not every XML document
can be represented in YAML/JSON ("naturally," there do exist some
extremely ugly 1:1 mappings. See also this post [1]). So if you use
XMLSchema as the definition of your data model, you may end up using
features that are not available under YAML/JSON if you are not careful.
[1] https://fedorahosted.org/pipermail/rhevm-api/2010-October/000419.html
* It doesn't give you all you need to fully automatically
create a
CLI. There is still hand-crafted metadata necessary to indicate e.g.
which elements are allowed and/or required for POST vs PUT. XMLSchema
cannot represent multiple types with the same element, and therefore you
cannot use XMLSchema itself to express these requirements if they are
different between e.g POST and PUT, which is almost always the case
(e.g. an attribute required for creation but non-updatable afterwards).
You could use custom annotations which XMLSchema supports, but then i
ask myself what's the point of using XMLSchema at all.
Yes, I agree an XML Schema does not do everything you need to define a RESTFul API. But
that is no downfall of an XSD, it is the fact that there is no formal way to define a
RESTFul API in any sense. An XSD works with SOAP because we have the notion of a formally
defined SOAP API in terms of a WSDL, but there is no equivilent for REST.
A RESTful API contains an almost complete description, albeit at
runtime, via the <link>s and via the OPTIONS method. That's the closest
you get to WSDL. I don't think you really want to go the way of defining
in an RPC fashion which "method calls" are available in a RESTful API.
In REST it's more natural to think in terms of constraints on entities.
I think it's fair to expect to be able to use a schema definition
language to model those constraints.
* The fact that it doesn't have un-ordered collections is just
silly.
In reality there's two options: either accept non-validating XML (which
is what rhevm-api does), or require all clients to be validating clients
using the schema. No human user will remember the way in which the
elements have to go.
This expresses 0 or more elements to be present in any order in the in the given
collection. You can override this: e.g.
<xs:all>
<xs:element ref="name" minOccurs="1"/>
</xs:all>
<xs:all> has a lot of limitations. It requires maxOccurs="1" and it
cannot be nested. In real life it's not usable.
Regards,
Geert
11:54 a.m.
Hi Geert,
So sort of moving from formal definitions to API types here :) and probably beyond my
knowledge :)
Yes I agree with how we should think about a RESTful API as not RPC based. I meant to use
SOAP just as an example.
I think a pre-runtime definition is what I want really, when I am implementing a client
for an API. I personally think this makes understanding the use of a client much easier,
and would also allow a lot of the code to be auto-generated for us. Which if there was
such a thing a formal RESTful definition would offer.
I haven't come across (yet) a use case where an XSD has failed to manage to describe
my data model. So its interesting to hear this and I would be interested to find out
more.
Thanks
Martyn
----- Original Message -----
From: "Geert Jansen" <gjansen(a)redhat.com>
To: "Martyn Taylor" <mtaylor(a)redhat.com>
Cc: "Mark McLoughlin" <markmc(a)redhat.com>, aeolus-devel(a)fedorahosted.org
Sent: Tuesday, 7 June, 2011 5:05:48 PM
Subject: Re: CLI - Formal XML Definition
On 06/07/2011 05:28 PM, Martyn Taylor wrote:
Some interesting points.
I'm going to sound like an XSD fiend here but:
No problem, i have no horse in this race.
Hi Martin, Mark,
On 06/07/2011 04:35 PM, Martyn Taylor wrote:
> Hi Mark,
>
> Thanks for this link, interesting.
>
> So it seems that RHEV-M does already provide an XML Schema (XSD). Which is the
approach I was trying to promote for our APIs. Creating this could be part of the CLI
effort?
>
> Quote:
> "The creation of the class hierarchy is tremendously more simple if an XMLSchema
code generator is avalailable for your language/platform. This is because the RHEV API
itself provides an XMLSchema file that defines all the objects. This file can be used with
a code generator to generate the classes automatically. The Python bindings use the
"PyXB" schema generator for example."
XMLSchema has certainly been very useful in the RHEVM API project. I
must say though that on the other side, XMLSchema has frustrated me
quite a bit when doing the RHEV-M Python SDK and CLI. There's a couple
of reasons:
* It's too rich. If you don't properly constrain yourself, it will be
difficult to use the XMLSchema to provide YAML and JSON bindings,
because those have a less rich data model (no distinction between
attributes/elements, order is relevant, etc).
Is it not a feature to have a rich data model? It seems YAML has taken a subset of XML
and implemented that. But anything you can define in YAML and JSON can be defined in XML
Correct, but it's the reverse that's the problem: not every XML document
can be represented in YAML/JSON ("naturally," there do exist some
extremely ugly 1:1 mappings. See also this post [1]). So if you use
XMLSchema as the definition of your data model, you may end up using
features that are not available under YAML/JSON if you are not careful.
[1] https://fedorahosted.org/pipermail/rhevm-api/2010-October/000419.html
* It doesn't give you all you need to fully automatically
create a
CLI. There is still hand-crafted metadata necessary to indicate e.g.
which elements are allowed and/or required for POST vs PUT. XMLSchema
cannot represent multiple types with the same element, and therefore you
cannot use XMLSchema itself to express these requirements if they are
different between e.g POST and PUT, which is almost always the case
(e.g. an attribute required for creation but non-updatable afterwards).
You could use custom annotations which XMLSchema supports, but then i
ask myself what's the point of using XMLSchema at all.
Yes, I agree an XML Schema does not do everything you need to define a RESTFul API. But
that is no downfall of an XSD, it is the fact that there is no formal way to define a
RESTFul API in any sense. An XSD works with SOAP because we have the notion of a formally
defined SOAP API in terms of a WSDL, but there is no equivilent for REST.
A RESTful API contains an almost complete description, albeit at
runtime, via the <link>s and via the OPTIONS method. That's the closest
you get to WSDL. I don't think you really want to go the way of defining
in an RPC fashion which "method calls" are available in a RESTful API.
In REST it's more natural to think in terms of constraints on entities.
I think it's fair to expect to be able to use a schema definition
language to model those constraints.
* The fact that it doesn't have un-ordered collections is just
silly.
In reality there's two options: either accept non-validating XML (which
is what rhevm-api does), or require all clients to be validating clients
using the schema. No human user will remember the way in which the
elements have to go.
This expresses 0 or more elements to be present in any order in the in the given
collection. You can override this: e.g.
<xs:all>
<xs:element ref="name" minOccurs="1"/>
</xs:all>
<xs:all> has a lot of limitations. It requires maxOccurs="1" and it
cannot be nested. In real life it's not usable.
Regards,
Geert
_______________________________________________
aeolus-devel mailing list
aeolus-devel(a)lists.fedorahosted.org
https://fedorahosted.org/mailman/listinfo/aeolus-devel
1:02 p.m.
On 06/07/2011 06:54 PM, Martyn Taylor wrote:
Hi Geert,
So sort of moving from formal definitions to API types here :) and probably beyond my
knowledge :)
Yes I agree with how we should think about a RESTful API as not RPC based. I meant to
use SOAP just as an example.
I think a pre-runtime definition is what I want really, when I am implementing a client
for an API. I personally think this makes understanding the use of a client much easier,
and would also allow a lot of the code to be auto-generated for us. Which if there was
such a thing a formal RESTful definition would offer.
That's a good point. A pre-runtime description is something that is
completely lacking today for the RHEV-M API. We (at least, I) sort of
accepted that. My thinking is that in the time of fast-moving APIs, you
really want to connect to a server to see what it has on offer, rather
than using a (cached) description locally of what you think the server has.
But i would still be very interested in such a pre-runtime definition
language, as it can also be used at runtime to efficiently transfer the
entire API in one go. We tried to create one for the RHEV-M API (dubbed
"RSDL," the m/l archives have some information on it) but it didn't
really work out. If you can create something simple and RESTful then i
think our project would be very interested. In my view it would
preferably not use XMLSchema as its type definition language but instead
something simpler and more specific to types in a RESTful context.
Regards,
Geert
4:57 a.m.
Hi Geert,
Sure I would be certainly interested in persueing this. In my opinion I think we should
really attempt to formally describe (pre-runtime) all our APIs.
It seems there are already some efforts to create a RESTful standard:
http://www.w3.org/Submission/wadl/ but still looks be in early stages.
I will attempt to describe the RHEV-M API using WADL and see how I get on, I will get back
to you with some results.
Thanks alot,
Martyn
----- Original Message -----
From: "Geert Jansen" <gjansen(a)redhat.com>
To: "Martyn Taylor" <mtaylor(a)redhat.com>
Cc: "Mark McLoughlin" <markmc(a)redhat.com>, aeolus-devel(a)fedorahosted.org
Sent: Tuesday, 7 June, 2011 7:02:21 PM
Subject: Re: CLI - Formal XML Definition
On 06/07/2011 06:54 PM, Martyn Taylor wrote:
Hi Geert,
So sort of moving from formal definitions to API types here :) and probably beyond my
knowledge :)
Yes I agree with how we should think about a RESTful API as not RPC based. I meant to
use SOAP just as an example.
I think a pre-runtime definition is what I want really, when I am implementing a client
for an API. I personally think this makes understanding the use of a client much easier,
and would also allow a lot of the code to be auto-generated for us. Which if there was
such a thing a formal RESTful definition would offer.
That's a good point. A pre-runtime description is something that is
completely lacking today for the RHEV-M API. We (at least, I) sort of
accepted that. My thinking is that in the time of fast-moving APIs, you
really want to connect to a server to see what it has on offer, rather
than using a (cached) description locally of what you think the server has.
But i would still be very interested in such a pre-runtime definition
language, as it can also be used at runtime to efficiently transfer the
entire API in one go. We tried to create one for the RHEV-M API (dubbed
"RSDL," the m/l archives have some information on it) but it didn't
really work out. If you can create something simple and RESTful then i
think our project would be very interested. In my view it would
preferably not use XMLSchema as its type definition language but instead
something simpler and more specific to types in a RESTful context.
Regards,
Geert
_______________________________________________
aeolus-devel mailing list
aeolus-devel(a)lists.fedorahosted.org
https://fedorahosted.org/mailman/listinfo/aeolus-devel
6:03 a.m.
Hi,
On 06/08/2011 11:57 AM, Martyn Taylor wrote:
Sure I would be certainly interested in persueing this. In my
opinion I think we should really attempt to formally describe (pre-runtime) all our APIs.
Great. I agree that's describing RESTful APIs would be useful, IFF if it
can be done easily and without having to apply an RPC lens on top of REST.
It seems there are already some efforts to create a RESTful standard:
http://www.w3.org/Submission/wadl/ but still looks be in early stages.
I will attempt to describe the RHEV-M API using WADL and see how I get on, I will get
back to you with some results.
I looked at WADL before, but it's a completely misguided attempt in my
view to provide a service descriptor for a RESTful API. It tries to be
RESTful (it introduces the concept of a "resource"), but then goes about
defining method call parameters to it. In my view, a RESTful description
would focus only mapping a single type for each resource, map a single
resource to a single collection, list all collections and their
hierarchy, and finally define constraints on types for the different
HTTP methods. I think that would get you relatively far already.
Regards,
Geert
Thanks alot,
Martyn
----- Original Message -----
From: "Geert Jansen"<gjansen(a)redhat.com>
To: "Martyn Taylor"<mtaylor(a)redhat.com>
Cc: "Mark McLoughlin"<markmc(a)redhat.com>, aeolus-devel(a)fedorahosted.org
Sent: Tuesday, 7 June, 2011 7:02:21 PM
Subject: Re: CLI - Formal XML Definition
On 06/07/2011 06:54 PM, Martyn Taylor wrote:
> Hi Geert,
>
> So sort of moving from formal definitions to API types here :) and probably beyond my
knowledge :)
>
> Yes I agree with how we should think about a RESTful API as not RPC based. I meant
to use SOAP just as an example.
>
> I think a pre-runtime definition is what I want really, when I am implementing a
client for an API. I personally think this makes understanding the use of a client much
easier, and would also allow a lot of the code to be auto-generated for us. Which if
there was such a thing a formal RESTful definition would offer.
That's a good point. A pre-runtime description is something that is
completely lacking today for the RHEV-M API. We (at least, I) sort of
accepted that. My thinking is that in the time of fast-moving APIs, you
really want to connect to a server to see what it has on offer, rather
than using a (cached) description locally of what you think the server has.
But i would still be very interested in such a pre-runtime definition
language, as it can also be used at runtime to efficiently transfer the
entire API in one go. We tried to create one for the RHEV-M API (dubbed
"RSDL," the m/l archives have some information on it) but it didn't
really work out. If you can create something simple and RESTful then i
think our project would be very interested. In my view it would
preferably not use XMLSchema as its type definition language but instead
something simpler and more specific to types in a RESTful context.
Regards,
Geert
_______________________________________________
aeolus-devel mailing list
aeolus-devel(a)lists.fedorahosted.org
https://fedorahosted.org/mailman/listinfo/aeolus-devel
_______________________________________________
aeolus-devel mailing list
aeolus-devel(a)lists.fedorahosted.org
https://fedorahosted.org/mailman/listinfo/aeolus-devel
--
Geert Jansen
Product Marketing Manager, Red Hat Enterprise Virtualization
Red Hat S.r.L. T: +39 348 1980079
Via Antonio da Recanate 1 E: gjansen(a)redhat.com
Milan 20124, Italy
12:13 p.m.
[About 2 months late to the party!]
Agreed with your points about XSD. I once worked on translating the
Google AdWords API into language bindings, and it was extremely
complex, because XSD is far _too_ flexible and somewhat under-
specified.
On Tue, Jun 07, 2011 at 04:47:23PM +0200, Geert Jansen wrote:
Maybe there's some stuff out there, but i'm not aware.
For libguestfs we wrote a custom generator:
http://git.annexia.org/?p=libguestfs.git;a=tree;f=generator;hb=HEAD
The files of interest are:
- generator_actions.ml : List of API calls
- generator_<...>.ml : Generator for language <...>
- generator_types.ml : Precise dscriptions of call and return types
Rich.
--
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
New in Fedora 11: Fedora Windows cross-compiler. Compile Windows
programs, test, and build Windows installers. Over 70 libraries supprt'd
http://fedoraproject.org/wiki/MinGW http://www.annexia.org/fedora_mingw
7:09 a.m.
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.
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.
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)
David
8:20 a.m.
Hi David,
----- Original Message -----
From: "David Lutterkort" <lutter(a)redhat.com>
To: "Martyn Taylor" <mtaylor(a)redhat.com>
Cc: aeolus-devel(a)fedorahosted.org
Sent: Wednesday, 8 June, 2011 1:09:11 PM
Subject: Re: CLI - Formal XML Definition
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.
The issue with proving documentation although human readable, is that it is almost always
not fully comprehensive, and sometimes out of sync with the codebase. Which I suppose
could be said about a formal definition should it not be updated. Another problem is that
it is not machine readable.
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.
Ruby and Python might not need ahead of time class generation, I'm sure others
languages too, but there are languages that would benefit from this. The main benefit of
marshalling objects to XML is to make it language independent. Even with this in mind, a
quick look at the code base for both these clients, and they have specific information in
there about the API. e.g. hwp_properties.rb (I'm not really familiar with this code
base, maybe there is some other reason for this).
I personally don't see a particularly large overhead in creating a formal definition,
I wrote one a while back for DC which probably took me a day, and the main timesync there
was figuring out what the XML actually looked like since the doc was so out of date
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.
Great, some better tools :)
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)
Firstly, XSDs are machine readable and there are tools that let you do things like class
generation or what ever else, which is a massive time saver in a language like Java.
I'm sure there are many other tools in many other languages that offer this + more
functionality, when providing a machine readable definition.
Secondly, and probably more importantly for me, is that they offers a clear, concise,
comprehensive and standard descriptions of the data model. Which from a developing
perspective is really what I want.
I'm not at all trying to advocate XSD, RelayNG, but since a data model in Aeolus uses
XML that would be a potential way to describe the model in a formal way.
If there are alternative solutions that offer the best of both worlds then awesome.
Offering a formal definition along side documentation would probably give us the best of
both worlds.
Cheers
Martyn
David
11:50 a.m.
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
4649
days inactive
4705
days old
aeolus-devel@lists.fedorahosted.org
13 comments
5 participants
participants (5)
-
David Lutterkort -
Geert Jansen -
Mark McLoughlin -
Martyn Taylor -
Richard W.M. Jones