PATCH, Expect, Prefer, etc

Ok, the recent conversation around the use of the 200/204 status codes
in the current PATCH draft has indicated that a couple of new status
codes and a new request header would likely be helpful. So how about
something like this:

---
208 Content Returned

The request has succeeded.  The information returned with the response
is equivalent to what would be returned in a subsequent GET on the resource.

418 Preference Failed

The preference given in a Prefer request-header field was understood by
could not be met by this server.

Prefer header

The Prefer request-header field is used to indicate that particular
server behaviors are preferred by the client.

  Prefer = "Prefer" ":" 1#preference

  preference  = "208-content-returned" |
                "204-no-content" |
                preference-extension

  preference-extension = token [ "=" ( token | quoted-string )
                         *preference-params ]

  preference-params = ";" token [ "=" ( token | quoted-string ) ]

A server that does not understand or is unable to comply with any of the
preference values in the Prefer field of a request MUST ignore those
values.  The server MAY response with a 418 (Preference Failed) status
if any of the preferences cannot be met.

This header field is defined with extensible syntax to allow for future
extensions.  If a server receives a request containing a Prefer field
that includes a preference-extension that it does not support, it MUST
ignore that extension.

Comparison of preference values is case-insensitive for unquoted tokens
including 208-content-returned and 204-no-content, and is case-sensitive
for quoted-string expectation-extensions.

The Prefer mechanism is hop-by-hop; that is, an HTTP/1.1 proxy MAY
fulfill a Preference if it receives a request with a preference it can
meet.  However, the Prefer request-header itself is end-to-end; it MUST
be forwarded if the request is forwarded.

A Prefer field that includes the 208-content-returned value indicates
that the client prefers that the server respond with a 208 status.

A Prefer field that includes the 204-no-content value indicates that the
client prefers that the server respond with a 204 status.
---

Example 1: Successful response, preference fulfilled

PATCH /foo HTTP/1.1
Prefer: 208-content-returned
Content-Type: ...

{patch document}


HTTP/1.1 208 Content Returned
Content-Type: ...
Etag: ...

{resource content}

---

Example 2: Successful response, preference fulfilled

PATCH /foo HTTP/1.1
Prefer: 204-no-content
Content-Type: ...

{patch document}


HTTP/1.1 204 No Content

---

Example: Successful response, preference ignored

PATCH /foo HTTP/1.1
Prefer: 208-content-returned
Content-Type: ...

{patch document}


HTTP/1.1 200 OK
Content-Type: ...
Warning: 601 server "Preference Ignored"

{some data}

---

Example: Successful response, preference fulfilled by a proxy rather
than the origin server

PATCH /foo HTTP/1.1
Prefer: 204-no-content
Content-Type: ...

{patch document}


HTTP/1.1 204 No-Content
Warning: 602 proxy "Preference Fulfilled


---

Example: Server chose not to fulfill or ignore the preference

PATCH /foo HTTP/1.1
Prefer: 208-content-returned
Content-Type: ...

{patch document}


HTTP/1.1 418 Preference Failed

{error response}

---

The Prefer header is defined to be generally identical to Expect with
the difference being that Prefer MUST be ignored if it is not
understood.  A server can choose not to fulfill a preference and
communicate that choice to the client using 418, but proxies are
required to forward them on.

A proxy can choose to fulfill a preference if it is capable.  For
instance, a proxy that receives a 200 or 209 response to a request that
contains Prefer: 204-no-content can choose to return 204 No Content to
the client rather than the complete original response.  If the request
contains 209-content-returned and the server responds with 200 or 204
(or whatever), then it obviously will not be capable of fulfilling the
preference and must ignore it.

Thoughts?

- James

Received on Friday, 3 August 2007 06:18:30 UTC