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

[Bryan Kearney]

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?

-- bk