Re: #332, was: Redirect fallback requirements

On 26/01/2012, at 6:30 AM, Julian Reschke wrote:

> 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

+1. Downgrade to prose?

> 
>   ... 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?

+1 

>   ...
> 
> 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).

Assuming you mean the second SHOULD, +1


> 
> 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"?

-1

I think this information is important.


>   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.

Doesn't hut to be specific, though. - 0.5

> 
> Best regards, Julian
> 

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

Received on Thursday, 26 January 2012 00:34:51 UTC