I propose that Rails and ActiveResource add support for retrieving a model's schema via REST. This could make it much easier for REST clients to auto-figure out attributes, the way that ActiveRecord uses the database to do the same thing.
The best location for this is, I think, at "/users/new.xml", using a "User" model as the example. The HTML at "/users/new" provides the form needed to create a new instance, and the XML version would provide the information needed to do the same thing remotely.
respond_to do |format| format.xml { render :xml => User.to_xml } end
This would mean writing a to_xml function on ActiveRecord::Base as a class method. The XML this produces could look like the normal AR to_xml format, just without any content. An example:
I've been working on an ActiveResource client in JavaScript, and it's impossible to just assign properties to an object and for the object to know that these are attributes to be submitted along with any POST or PUT call. ActiveResource has a partial solution to this by taking advantage of Ruby's method_missing, so any unknown properties that get assigned can be caught and recognized as formal attributes. Clients written in strongly typed languages would have an even harder time than JavaScript. Including an easy way to advertise the schema would ease the burden of any REST client.
More generally, I think this makes the Rails REST standard more complete, by affording an ActiveResource client the same level of schema knowledge that an ActiveRecord server has.
What do you guys think? Would this be a useful extension to the current REST standard Rails is advocating? I think the most interesting part of this is the XML format, and I'd really like to form something the community agrees with as I construct a patch for this.
> What do you guys think? Would this be a useful extension to the > current REST standard Rails is advocating? I think the most > interesting part of this is the XML format, and I'd really like to > form something the community agrees with as I construct a patch for > this.
I like! I do think a little more metadata would make it easier to build loosely coupled systems around REST and Rails.
> respond_to do |format| > format.xml { render :xml => User.to_xml } > end
> This would mean writing a to_xml function on ActiveRecord::Base as a > class method. The XML this produces could look like the normal AR > to_xml format, just without any content. An example:
Why not generate an xml schema? or RelaxNG? Inventing a schema language seems like the wrong direction...
> More generally, I think this makes the Rails REST standard more > complete, by affording an ActiveResource client the same level of > schema knowledge that an ActiveRecord server has.
> > respond_to do |format| > > format.xml { render :xml => User.to_xml } > > end
> > This would mean writing a to_xml function on ActiveRecord::Base as a > > class method. The XML this produces could look like the normal AR > > to_xml format, just without any content. An example:
> Why not generate an xml schema? or RelaxNG? Inventing a schema > language seems like the wrong direction...
> > More generally, I think this makes the Rails REST standard more > > complete, by affording an ActiveResource client the same level of > > schema knowledge that an ActiveRecord server has.
> And that looks more complicated than it needs to be.
Depends on what your requirements are. If you want a 'schema language' to help non-rails clients, why not use one that's been widely tested and has support in many different languages. Making up something specific for rails would mean it's of questionable value to non-rails programming environments.
I'm not necessarily sold on the idea of generating a particular schema language, or even of generating a schema at all, but I do know that inventing our own is something we should be very wary of.
Michael Koziarski wrote: >> And that looks more complicated than it needs to be.
> Depends on what your requirements are. If you want a 'schema > language' to help non-rails clients, why not use one that's been > widely tested and has support in many different languages. Making up > something specific for rails would mean it's of questionable value to > non-rails programming environments.
> I'm not necessarily sold on the idea of generating a particular schema > language, or even of generating a schema at all, but I do know that > inventing our own is something we should be very wary of.
> I propose that Rails and ActiveResource add support for retrieving a > model's schema via REST. This could make it much easier for REST > clients to auto-figure out attributes, the way that ActiveRecord uses > the database to do the same thing.
+1, I think this is a great idea.
Since we're talking about this, I had the idea of using the OPTIONS method to return the methods allowed on a resource (via the Allow header), but also returning an XML representation of the routes for the nested and associated resources.
The OPTIONS response is supposed to return a comma separated list of methods allowed in the Allow header, but the body can really be anything we want since the spec doesn't say what it should be. If people think this is a good fit, we could use it as a way of "introspecting" a resource.
Combine these two ideas, and we have a way for a remote client to create new resources AND a way of finding all the associated resources.
--
Thanks,
Dan __________________________________________________________________
On Sat, Apr 21, 2007 at 12:29:30PM +1200, Michael Koziarski wrote: > Depends on what your requirements are. If you want a 'schema > language' to help non-rails clients, why not use one that's been > widely tested and has support in many different languages. Making up > something specific for rails would mean it's of questionable value to > non-rails programming environments.
Along these lines, I've been investigating generating a W3C XML Schema from a model and found it delightfully easy with just a bit of reflection on AR::Base::columns. Throw in a .xsd format and you've got a great place to serve your schema.
One of the things I noticed was how similar the standard types for an XML Schema were to the types used by #to_xml. With just a few very slight changes, Rails can be using a standardized list of types instead of inventing its own.
I've refactored part of Hash::from_xml and in the process, added support for the parsing end of things for these types. This also fixes a few issues as noted in the ticket I submitted it with. It goes without saying tests are included. If there's interest, I can fix up the generating part (the various #to_xml's) as well.
> I'm not necessarily sold on the idea of generating a particular schema > language, or even of generating a schema at all, but I do know that > inventing our own is something we should be very wary of.
I agree, most of this is destined for plugin land at most. But I think reusing the types in the core is a Good Thing.
On Sat, Apr 21, 2007 at 04:23:03PM -0700, Dr. Ernie Prabhakar wrote: > > If there's interest, I can > > fix up the generating part (the various #to_xml's) as well.
> Wow, great work. I'd certainly be interested in seeing that...
Okay. I see that my first patch was committed this morning (thanks DHH) so this is the next logical step. Note that by itself, this change enables nothing without a proper schema definition. Basically it would be trading a little bit of aesthetics (e.g., datetime for dateTime) for a little bit of purity (a "standard" type list).
On the subject of XML schemas, the biggest missing piece of the puzzle is a way to get the appropriate attributes on the root element for records. I am thinking an interface would look something like
> Okay. I see that my first patch was committed this morning (thanks > DHH) so this is the next logical step. Note that by itself, this > change enables nothing without a proper schema definition. Basically > it would be trading a little bit of aesthetics (e.g., datetime for > dateTime) for a little bit of purity (a "standard" type list).
Could you elaborate here a bit and list the changes needed to the current AR::to_xml method to make it W3C compliant? This sounds like a good idea, though I'm curious as to how heavy the aesthetics- standards tradeoff will be.
> On the subject of XML schemas, the biggest missing piece of the puzzle > is a way to get the appropriate attributes on the root element for > records. I am thinking an interface would look something like
> I'm not necessarily sold on the idea of generating a particular schema > language, or even of generating a schema at all, but I do know that > inventing our own is something we should be very wary of.
RelaxNG is a schema for *XML*, not for a *model*. This schema is only indirectly used to construct XML POSTs/PUTs, its primary use is for the client to understand the makeup of your data. In fact, "Elements" and "text nodes" aren't the correct conceptual way to describe a data model.
In fact, consider that a RelaxNG schema would be outright inaccurate unless you label every single element in the schema as optional. You can update as few or as many attributes as you like in a PUT, and you may never be interested in including data for associations in your requests, yet you probably want to note all attributes and associations in a schema for the model. The way you label elements as optional in RelaxNG seems to be just "zeroOrMore". This terminology should be used only to describe the nature of associations between data, not just to make sure the flexible nature of REST is described technically accurately.
So, I think RelaxNG is inappropriate for a simple, flexible description of a data model, and that we should keep the format as close to the current AR#to_xml format as possible.
