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