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/doc...
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@lists.fedorahosted.org https://fedorahosted.org/mailman/listinfo/deltacloud-devel
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/doc...
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.
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@redhat.com To: "Martyn Taylor" mtaylor@redhat.com Cc: gjansen@redhat.com, aeolus-devel@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/doc...
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@lists.fedorahosted.org https://fedorahosted.org/mailman/listinfo/aeolus-devel
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
Hi Geert,
Some interesting points.
I'm going to sound like an XSD fiend here but:
----- Original Message ----- From: "Geert Jansen" gjansen@redhat.com To: "Martyn Taylor" mtaylor@redhat.com Cc: "Mark McLoughlin" markmc@redhat.com, aeolus-devel@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@lists.fedorahosted.org https://fedorahosted.org/mailman/listinfo/aeolus-devel
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
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@redhat.com To: "Martyn Taylor" mtaylor@redhat.com Cc: "Mark McLoughlin" markmc@redhat.com, aeolus-devel@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@lists.fedorahosted.org https://fedorahosted.org/mailman/listinfo/aeolus-devel
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
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@redhat.com To: "Martyn Taylor" mtaylor@redhat.com Cc: "Mark McLoughlin" markmc@redhat.com, aeolus-devel@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@lists.fedorahosted.org https://fedorahosted.org/mailman/listinfo/aeolus-devel
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@redhat.com To: "Martyn Taylor"mtaylor@redhat.com Cc: "Mark McLoughlin"markmc@redhat.com, aeolus-devel@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@lists.fedorahosted.org https://fedorahosted.org/mailman/listinfo/aeolus-devel _______________________________________________ aeolus-devel mailing list aeolus-devel@lists.fedorahosted.org https://fedorahosted.org/mailman/listinfo/aeolus-devel
[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.
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
Hi David,
----- Original Message ----- From: "David Lutterkort" lutter@redhat.com To: "Martyn Taylor" mtaylor@redhat.com Cc: aeolus-devel@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
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
aeolus-devel@lists.fedorahosted.org