Changeset 1257 for draft-ietf-httpbis/latest/p2-semantics.xml

Timestamp:

Apr 4, 2011, 7:46:15 AM (9 years ago)

Author:

fielding@…

Message:

editorial: rephrase definition of the 204 No Content status code
to be (hopefully) clearer about server expectations rather than a
SHOULD requirement on a specific UI.

File:

• draft-ietf-httpbis/latest/p2-semantics.xml (modified) (1 diff)

draft-ietf-httpbis/latest/p2-semantics.xml

@@ -1398 +1398 @@
   <iref primary="true" item="Status Codes" subitem="204 No Content" x:for-anchor=""/>
 <t>
-   The server has successfully fulfilled the request, but there is no
-   additional content to return in the response payload body.  The
-   resource metadata and representation metadata in the response message's
-   header fields refer to the target resource
-   and its current representation, respectively, after the requested action.
+   The 204 (No Content) status code indicates that the server has
+   successfully fulfilled the request and that there is no additional
+   content to return in the response payload body.  Metadata in the
+   response header fields refer to the target resource and its current
+   representation after the requested action.
+</t>
+<t>
    For example, if a 204 status code is received in response to a PUT
-   and the response contains an ETag header field, then the value of
-   that field is the current entity-tag for the representation that
-   was successfully PUT.
-</t>
-<t>
-   If the client is a user agent, it &SHOULD-NOT; change its document view
-   from that which caused the request to be sent. This response is
-   primarily intended to allow input for actions to take place without
-   causing a change to the user agent's active document view, although
-   any new or updated metadata &SHOULD; be applied to the document
-   currently in the user agent's active view.
+   request and the response contains an ETag header field, then the PUT
+   was successful and the ETag field-value contains the entity-tag for
+   the new representation of that target resource.
+</t>
+<t>
+   The 204 response allows a server to indicate that the action has been
+   successfully applied to the target resource while implying that the
+   user agent &SHOULD-NOT; traverse away from its current "document view"
+   (if any).  The server assumes that the user agent will provide some
+   indication of the success to its user, in accord with its own interface,
+   and apply any new or updated metadata in the response to the active
+   representation.
+   For example, a 204 status code is commonly used with document editing
+   interfaces corresponding to a "save" action, such that the document
+   being saved remains available to the user for editing. It is also
+   frequently used with interfaces that expect automated data transfers
+   to be prevalent, such as within distributed version control systems.
 </t>
 <t>