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