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

[David Lutterkort]

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