REST Service Description Documents?

Hi all,

I'm really excited about the new RESTful features coming in Rails 1.2. I am also intrigued by the work going on into ActiveResource, as a consumer of RESTful web services. However -- and I apologize if this is just my own ignorance -- I'm a little unclear on how the "impedance matching" between them gets done.

In particular (to my embarrassment :), I just now learned that Atom's "Introspection" feature now goes by the name "Service Documents":

http://www-128.ibm.com/developerworks/library/x-atompp1/

Naively, it would seem that these map pretty closely to the functionality provided by Rails 1.2. In fact, with the appropriate mime types, it seems like we might be able to autogenerate these for -every- Rails application, not just XML web services.

So, my question is:

a) Is my characterization of the situation accurate?

b) Is this something worth pursuing?

c) Has anyone done any work on something like this?

d) Should I spend Christmas break working on plugin? :slight_smile:

Thanks,
-- Ernie P.

I'm really excited about the new RESTful features coming in Rails
1.2. I am also intrigued by the work going on into ActiveResource, as
a consumer of RESTful web services. However -- and I apologize if
this is just my own ignorance -- I'm a little unclear on how the
"impedance matching" between them gets done.

I'm not entirely sure what you mean by "impedance matching". Are you
talking about how to make Rails 1.2 and ActiveResource follow the same
conventions for, say, URL structure? By default ARes will assume that
the application is using the default Rails conventions. So unless you
change anything, everything should Just Work. If you start diverging
from the Rails conventions, you'll naturally have to specify those
diverges in your ARes models.

b) Is this something worth pursuing?

I'm not sure whether servicedocuments make sense for
application-specific APIs. As I understand it, the service document for
APP makes sense because it relies on the rest of APP. So when it says
<accept>entry</accept>, that makes sense because entry is a defined
entity and someone could do something automatic based on that.

But if you have <accept>invoice</accept>, I'm not sure what you'd be
able to use that information for?

To me, it looks like service documents are great for APP consumers that
have already generically implemented the protocol and will then be able
to ask any APP provider what it can do and how. For app-specific APIs,
like the default ones Rails generate, I don't know how something like
that could be automatically consumed.

d) Should I spend Christmas break working on plugin? :slight_smile:

I'd personally love to see an APP implementation using the Rails 1.2
REST features. Just a simple blog working completely would APP would be
a great way to spend a Christmas break ;).

-- david

> d) Should I spend Christmas break working on plugin? :slight_smile:

On a somewhat related note, I have a plugin which can generate
relaxng schemas (compact and regular) for active record objects. I
abandoned it before release as I had no real production requirement
for it, but it was fun to hack on from bangkok international airport
while waiting (8 hours) for my flight back home.

The api is in two parts, creating 'schema' objects and serializing
them. Something like:

RelaxingSchema::Schema.build(Person, :include=>[:group, :addresses]).serialize

element person {
  element id { xsd:int, attribute type { "integer" } }
  &element name { text }
  &element created-at { xsd:dateTime, attribute type { "datetime" } }
  &element group-id { xsd:int, attribute type { "integer" } }
  &element group {
    element id { xsd:int, attribute type { "integer" } }
    &element name { text }
  } ?

  &element addresses {
    element address {
      element id { xsd:int, attribute type { "integer" } }
      &element body { text }
      &element dpid { xsd:int, attribute type { "integer" } }
      &element created-on { xsd:date, attribute type { "date" } }
      &element person-id { xsd:int, attribute type { "integer" } }
    }*
  }?
}

If you're interested in this kind of functionality, just let me know
and I'd be happy to stick the code somewhere publically accessible.