Revision of p2 2.2.1 / who can generate a status code?

<https://svn.tools.ietf.org/svn/wg/httpbis/draft-ietf-httpbis/latest/p2-semantics.html#considerations.for.new.methods> currently has:

> When it is necessary to express new semantics for a HTTP request that aren't specific to a single application or media type, and currently defined methods are inadequate, it might be appropriate to register a new method.
> 
> HTTP methods are generic; that is, they are potentially applicable to any resource, not just one particular media type, "type" of resource, or application. As such, it is preferred that new HTTP methods be registered in a document that isn't specific to a single application, so that this is clear.
> 
> Due to the parsing rules defined in Section 3.3 of [Part1], definitions of HTTP methods cannot prohibit the presence of a message body on either the request or the response message (with responses to HEAD requests being the single exception). Definitions of new methods cannot change this rule, but they can specify that only zero-length bodies (as opposed to absent bodies) are allowed.
> 
> New method definitions need to indicate whether they are safe (Section 2.1.1), what semantics (if any) the request body has, and whether they are idempotent (Section 2.1.2). They also need to state whether they can be cached ([Part6]); in particular what conditions a cache may store the response, and under what conditions such a stored response may be used to satisfy a subsequent request.

Based on discussion, I suggest it be replaced with:

"""
When it is necessary to express new semantics for a HTTP request that aren't specific to a single application or media type, and currently defined methods are inadequate, it might be appropriate to register a new method.

HTTP methods are generic; that is, they are potentially applicable to any resource, not just one particular media type, "type" of resource, or application. As such, it is preferred that new HTTP methods be registered in a document that isn't specific to a single application, so that this is clear.

Due to the parsing rules defined in Section 3.3 of [Part1], definitions of HTTP methods cannot prohibit the presence of a message body on either the request or the response message (with responses to HEAD requests being the single exception). Definitions of new methods cannot change this rule, but they can specify that only zero-length bodies (as opposed to absent bodies) are allowed.

Definitions of new methods need to indicate:

* whether they are safe (Section 2.1.1),
* whether they are idempotent (Section 2.1.2),
* what semantics (if any) the request body has,
* whether proxies, origin servers (including gateways), intermediaries (proxy or gateway) or all servers can generate this status code,
* whether they can be cached ([Part6]); in particular what conditions a cache may store the response, and under what conditions such a stored response may be used to satisfy a subsequent request.
"""

Note that the new consideration -- identifying who can generate the status code -- implies (as Julian pointed out) that we should eat our own dogfood and define it for ours.

Looking through p2, this was actually easier than I thought it might be; most of the status codes already are pretty specific (using phrases like "the resource indicates...", which can logically be read to make it specific to origins). The only issues of interpretation I found are marked by "!" below.

O - Origin server (including gateways)
I - Intermediaries (proxy or gateway)
P - Proxies (not gateways)
S - All servers

 Informational 1xx
S   100 Continue
S   101 Switching Protocols

 Successful 2xx
O   200 OK
O   201 Created
O   202 Accepted
P   203 Non-Authoritative Information
O   204 No Content
O   205 Reset Content

 Redirection 3xx
O   300 Multiple Choices
O   301 Moved Permanently
O   302 Found
O   303 See Other
    305 Use Proxy
    306 (Unused)
O   307 Temporary Redirect

 Client Error 4xx
S   400 Bad Request
    402 Payment Required
O!  403 Forbidden
O   404 Not Found
O   405 Method Not Allowed
O   406 Not Acceptable
S   408 Request Timeout
O   409 Conflict
O   410 Gone
S   411 Length Required
S   413 Request Representation Too Large
S   414 URI Too Long
O   415 Unsupported Media Type
S   417 Expectation Failed
S   426 Upgrade Required

 Server Error 5xx
S   500 Internal Server Error
O!   501 Not Implemented
I   502 Bad Gateway
S   503 Service Unavailable
I   504 Gateway Timeout
S   505 HTTP Version Not Supported


Thoughts?

--
Mark Nottingham   http://www.mnot.net/

Received on Tuesday, 3 July 2012 02:00:32 UTC