- From: Julian Reschke <julian.reschke@gmx.de>
- Date: Wed, 25 Jan 2012 20:30:07 +0100
- To: Mark Nottingham <mnot@mnot.net>
- CC: Bjoern Hoehrmann <derhoermi@gmx.net>, HTTP Working Group <ietf-http-wg@w3.org>
On 2012-01-25 01:07, Julian Reschke wrote:
> ...
> The question remains whether we should relax more of the SHOULD-level
> requirements on response payloads. At least some of them seem fishy (not
> necessarily the 3xx ones). Will send separate mail later this week.
> ...
Here we go; excerpts from P2 Section 7:
7.2.2. 201 Created
The request has been fulfilled and has resulted in a new resource
being created. The newly created resource can be referenced by the
URI(s) returned in the payload of the response, with the most
specific URI for the resource given by a Location header field. The
response SHOULD include a payload containing a list of resource
characteristics and location(s) from which the user or user agent can
choose the one most appropriate. ...
This seems fishy. In particular it makes little sense for PUT->2
... The payload format is specified by
the media type given in the Content-Type header field.
Some status codes descriptions state this, some do not. It is always
true, however. Maybe just say this once at the beginning of Section 7?
...
7.2.3. 202 Accepted
The request has been accepted for processing, but the processing has
not been completed. The request might or might not eventually be
acted upon, as it might be disallowed when processing actually takes
place. There is no facility for re-sending a status code from an
asynchronous operation such as this.
The 202 response is intentionally non-committal. Its purpose is to
allow a server to accept a request for some other process (perhaps a
batch-oriented process that is only run once per day) without
requiring that the user agent's connection to the server persist
until the process is completed. The representation returned with
this response SHOULD include an indication of the request's current
status and either a pointer to a status monitor or some estimate of
when the user can expect the request to be fulfilled.
This one makes sense...
...
7.3.1. 300 Multiple Choices
The target resource has more than one representation, each with its
own specific location, and agent-driven negotiation information
(Section 5 of [Part3]) is being provided so that the user (or user
agent) can select a preferred representation by redirecting its
request to that location.
Unless it was a HEAD request, the response SHOULD include a
This one makes sense.
representation containing a list of representation metadata and
location(s) from which the user or user agent can choose the one most
appropriate. The data format is specified by the media type given in
the Content-Type header field. Depending upon the format and the
capabilities of the user agent, selection of the most appropriate
choice MAY be performed automatically. However, this specification
does not define any standard for such automatic selection.
If the server has a preferred choice of representation, it SHOULD
include the specific URI for that representation in the Location
field; user agents MAY use the Location field value for automatic
redirection.
Caches MAY use a heuristic (see Section 2.3.1.1 of [Part6]) to
determine freshness for 300 responses.
7.3.2. 301 Moved Permanently
The target resource has been assigned a new permanent URI and any
future references to this resource SHOULD use one of the returned
URIs. Clients with link editing capabilities ought to automatically
re-link references to the effective request URI to one or more of the
new references returned by the server, where possible.
Caches MAY use a heuristic (see Section 2.3.1.1 of [Part6]) to
determine freshness for 301 responses.
The new permanent URI SHOULD be given by the Location field in the
response. Unless the request method was HEAD, the representation of
the response SHOULD contain a short hypertext note with a hyperlink
to the new URI(s).
Björn says this is too strong; maybe demote to "ought to"? (The same
applies to 302 and 307).
...
7.4.4. 403 Forbidden
The server understood the request, but refuses to authorize it.
Providing different user authentication credentials might be
successful, but any credentials that were provided in the request are
insufficient. The request SHOULD NOT be repeated with the same
credentials.
If the request method was not HEAD and the server wishes to make
public why the request has not been fulfilled, it SHOULD describe the
reason for the refusal in the representation. If the server does not
wish to make this information available to the client, the status
code 404 (Not Found) MAY be used instead.
This one seems ok to me.
...
7.4.7. 406 Not Acceptable
The resource identified by the request is only capable of generating
response representations which have content characteristics not
acceptable according to the Accept and Accept-* header fields sent in
the request (see Section 6 of [Part3]).
Unless it was a HEAD request, the response SHOULD include a
representation containing a list of available representation
Seems ok to me.
characteristics and location(s) from which the user or user agent can
choose the one most appropriate. The data format is specified by the
media type given in the Content-Type header field. Depending upon
the format and the capabilities of the user agent, selection of the
most appropriate choice MAY be performed automatically. However,
this specification does not define any standard for such automatic
selection.
Note: HTTP/1.1 servers are allowed to return responses which are
not acceptable according to the accept header fields sent in the
request. In some cases, this might even be preferable to sending
a 406 response. User agents are encouraged to inspect the header
fields of an incoming response to determine if it is acceptable.
If the response could be unacceptable, a user agent SHOULD
temporarily stop receipt of more data and query the user for a
decision on further actions.
...
7.4.10. 409 Conflict
The request could not be completed due to a conflict with the current
state of the resource. This code is only allowed in situations where
it is expected that the user might be able to resolve the conflict
and resubmit the request. The response body SHOULD include enough
"ought to"?
information for the user to recognize the source of the conflict.
Ideally, the response representation would include enough information
for the user or user agent to fix the problem; however, that might
not be possible and is not required.
Conflicts are most likely to occur in response to a PUT request. For
example, if versioning were being used and the representation being
PUT included changes to a resource which conflict with those made by
an earlier (third-party) request, the server might use the 409
response to indicate that it can't complete the request. In this
case, the response representation would likely contain a list of the
differences between the two versions in a format defined by the
response Content-Type.
...
7.4.19. 426 Upgrade Required
The request can not be completed without a prior protocol upgrade.
This response MUST include an Upgrade header field (Section 8.7 of
[Part1]) specifying the required protocols.
Example:
HTTP/1.1 426 Upgrade Required
Upgrade: HTTP/3.0
Connection: Upgrade
Content-Length: 53
Content-Type: text/plain
This service requires use of the HTTP/3.0 protocol.
The server SHOULD include a message body in the 426 response which
indicates in human readable form the reason for the error and
describes any alternative courses which may be available to the user.
Seems ok to me.
7.5. Server Error 5xx
Response status codes beginning with the digit "5" indicate cases in
which the server is aware that it has erred or is incapable of
performing the request. Except when responding to a HEAD request,
the server SHOULD include a representation containing an explanation
of the error situation, and whether it is a temporary or permanent
condition. User agents SHOULD display any included representation to
the user. These response codes are applicable to any request method.
Seems ok to me.
...
7.5.6. 505 HTTP Version Not Supported
The server does not support, or refuses to support, the protocol
version that was used in the request message. The server is
indicating that it is unable or unwilling to complete the request
using the same major version as the client, as described in Section
2.6 of [Part1], other than with this error message. The response
SHOULD contain a representation describing why that version is not
supported and what other protocols are supported by that server.
This may not be needed given the text for 5xx.
Best regards, Julian
Received on Wednesday, 25 January 2012 19:30:51 UTC