[rest-practices] Read-only fields in a representation type

[David Lutterkort]

On Mon, 2010-04-26 at 08:14 -0400, Bryan Kearney wrote:
> On 04/23/2010 11:20 AM, David Lutterkort wrote:
> > On Fri, 2010-04-23 at 09:24 -0400, Bill Burke wrote:
> >> I think this blurb from one of the blogs describes what I mean perfectly:
> >>
> >> "And an IDL is simply a list of API signatures. It doesn't describe
> >> expected message exchange patterns, required authentication methods,
> >> message traffic limits, quality of service guarantees, or even pre and
> >> post conditions for the various method calls. You usually find this
> >> information in the documentation and/or in the actual business contract
> >> one signed with the Web service provider. A WADL document for the REST
> >> Web service will not change this fact."
> >
> > Nicely put. I assume that implies that API docs should be in POE (plain
> > old English) - I am all for that, since I really doubt that any formal
> > API spec will ever be up-to-date with the code or get real use by
> > clients.
> >
> > In theory (as in: if they weren't so annoying to write, I'd write them),
> > RelaxNG schemas for XML returned are useful mostly for testing the API
> > against inadvertant schema changes.
> >
> > On a tangent, for Deltacloud core, we have a simple system that
> > generates what parameters are accepted for each operation from the code.
> > I wouldn't call that API documentation in any formal sense, more a
> > gentle reminder to the API user of what's available and how.
> >
> > David
> >
> >
> What is the system?

It's the 'Rabbit DSL' in server/lib/sinatra/rabbit.rb. Best to look at
how it's used in server/server.rb.

If you have a running driver, go to http://localhost:3001/api/docs for a
list of known collections, and for each collection a list of operations
on them, together with acceptable parameters (the latter is changed on
server start, depending on the features the driver provides)

I'd like to eventually integrate that with the results of the API
proper, but I think it needs to solidify a little more before we can do
that.

David