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