A proposal for clarification to section 4.3 HTTP POST

I would like to propose a modification to section 4.1 HTTP POST, which will
I think is useful clarification without too much bloat.

Current Text:

*4.3 HTTP POST*
>
> This specification adds no new requirements on HTTP POST for LDPRs.
>

Recommended Text:

*4.3 HTTP POST*
>
> This specification adds no new requirements on HTTP POST for LDPRs that
> differ from those already provided in the HTTP/1.1 specification (RFC2616).
> While POST can be used for a variety of functions, it is most particularly
> intended to be used for the creation of new resources.
> Readers should note that PUT MAY also be used for the creation of new
> resources (see 4.4.6).
>

I just think we would do well to try to make less assumptions on the
reader's knowledge and provide brief hints that give a little confirmation
to what the reader is probably already assuming (for comfort).
So, in this case, now that I've clarified that we're referring to the
HTTP/1.1 spec, I summarize the most salient point(s) from there so that it
is not necessary to do a cross-check.
"Ah, yup... ok... POST for create... maybe also PUT...".

While the spec may be studied in scrupulous detail by some, it's probably
just going to be scanned by many more. I would expect to see at least one
salient point under the headline, not just a reference to some other spec.

-- 
Cody Burleson

Received on Saturday, 23 March 2013 16:43:28 UTC