From af7257eea046a51a27f300b58b9e05c6d0dbb6c1 Mon Sep 17 00:00:00 2001 From: Samuel Ryan Date: Mon, 9 Nov 2015 01:06:31 +0000 Subject: [PATCH] Improves 3xx class status codes with references --- contents/codes/300.md | 33 ++++++++++++++++++++------------- contents/codes/301.md | 16 +++++++++------- contents/codes/302.md | 13 +++++++------ contents/codes/303.md | 11 ++++++----- contents/codes/304.md | 14 ++++++++------ contents/codes/305.md | 9 +++++---- contents/codes/307.md | 18 ++++++++++-------- contents/codes/308.md | 39 ++++++++++++++++++++++----------------- 8 files changed, 87 insertions(+), 66 deletions(-) diff --git a/contents/codes/300.md b/contents/codes/300.md index 2a12a43..2cb2e46 100644 --- a/contents/codes/300.md +++ b/contents/codes/300.md @@ -6,13 +6,14 @@ references: "Rails HTTP Status Symbol": ":multiple_choices" --- -The 300 Multiple Choices status code indicates that the target resource has -more than one representation, each with its own more specific identifier, and -information about the alternatives is being provided so that the user (or user -agent) can select a preferred representation by redirecting its request to one -or more of those identifiers. In other words, the server desires that the user -agent engage in reactive negotiation to select the most appropriate -representation(s) for its needs ([RFC7231 Section 3.4][2]). +The target resource has more than one representation, each with its own more +specific identifier, and information about the alternatives is being provided +so that the user (or user agent) can select a preferred representation by +redirecting its request to one or more of those identifiers. + +In other words, the server desires that the user agent engage in reactive +negotiation to select the most appropriate representation(s) for its +needs[1](#ref-1). If the server has a preferred choice, the server SHOULD generate a Location header field containing a preferred choice's URI reference. The user agent MAY @@ -29,19 +30,25 @@ format believed to be acceptable to the user agent, as determined by shared design or content negotiation, or in some commonly accepted hypertext format. A 300 response is cacheable by default; i.e., unless otherwise indicated by the -method definition or explicit cache controls (see -[Section 4.2.2 of RFC7234][3]). +method definition or explicit cache controls[2](#ref-2). Note: The original proposal for the 300 status code defined the URI header field as providing a list of alternative representations, such that it would be usable for 200, 300, and 406 responses and be transferred in responses to the HEAD method. However, lack of deployment and disagreement over syntax led to both URI and Alternates (a subsequent proposal) being dropped from this specification. It -is possible to communicate the list using a set of Link header fields -[[RFC5988][4]], each with a relationship of "alternate", though deployment is a -chicken-and-egg problem. +is possible to communicate the list using a set of Link header +fields[3](#ref-3), each with a relationship of "alternate", +though deployment is a chicken-and-egg problem. -Source: [RFC7231 Section 6.4.1][1] +--- + +* 1 Content Negotiation +[RFC7231 Section 3.4][2] +* 2 Calculating Heuristic Freshness +[Section 4.2.2 of RFC7234][3] +* 3 Web Linking [RFC5988][4] +* Source: [RFC7231 Section 6.4.1][1] [1]: [2]: diff --git a/contents/codes/301.md b/contents/codes/301.md index ad768b8..79e649a 100644 --- a/contents/codes/301.md +++ b/contents/codes/301.md @@ -6,9 +6,8 @@ references: "Rails HTTP Status Symbol": ":moved_permanently" --- -The 301 Moved Permanently status code indicates that the target resource has -been assigned a new permanent URI and any future references to this resource -ought to use one of the enclosed URIs. +The target resource has been assigned a new permanent URI and any future +references to this resource ought to use one of the enclosed 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 sent by the @@ -21,13 +20,16 @@ usually contains a short hypertext note with a hyperlink to the new URI(s). Note: For historical reasons, a user agent MAY change the request method from POST to GET for the subsequent request. If this behavior is undesired, the -[307 (Temporary Redirect)](/307) status code can be used instead. +[307 Temporary Redirect](/307) status code can be used instead. A 301 response is cacheable by default; i.e., unless otherwise indicated by the -method definition or explicit cache controls -(see [Section 4.2.2 of [RFC7234]][2]). +method definition or explicit cache controls[1](#ref-1). -Source: [RFC7231 Section 6.4.2][1] +--- + +* 1 Calculating Heuristic Freshness +[RFC7234 Section 4.2.2][2] +* Source: [RFC7231 Section 6.4.2][1] [1]: [2]: \ No newline at end of file diff --git a/contents/codes/302.md b/contents/codes/302.md index 64812c4..562b19c 100644 --- a/contents/codes/302.md +++ b/contents/codes/302.md @@ -6,10 +6,9 @@ references: "Rails HTTP Status Symbol": ":found" --- -The 302 Found status code indicates that the target resource resides temporarily -under a different URI. Since the redirection might be altered on -occasion, the client ought to continue to use the effective request URI for -future requests. +The target resource resides temporarily under a different URI. Since the +redirection might be altered on occasion, the client ought to continue to use +the effective request URI for future requests. The server SHOULD generate a Location header field in the response containing a URI reference for the different URI. The user agent MAY use the Location field @@ -18,8 +17,10 @@ a short hypertext note with a hyperlink to the different URI(s). Note: For historical reasons, a user agent MAY change the request method from POST to GET for the subsequent request. If this behavior is undesired, the -[307 (Temporary Redirect)](/307) status code can be used instead. +[307 Temporary Redirect](/307) status code can be used instead. -Source: [RFC7231 Section 6.4.3][1] +--- + +* Source: [RFC7231 Section 6.4.3][1] [1]: \ No newline at end of file diff --git a/contents/codes/303.md b/contents/codes/303.md index fb6dab2..229aabc 100644 --- a/contents/codes/303.md +++ b/contents/codes/303.md @@ -6,10 +6,9 @@ references: "Rails HTTP Status Symbol": ":see_other" --- -The 303 See Other status code indicates that the server is redirecting the -user agent to a different resource, as indicated by a URI in the Location header -field, which is intended to provide an indirect response to the original -request. +The server is redirecting the user agent to a different resource, as indicated +by a URI in the Location header field, which is intended to provide an indirect +response to the original request. A user agent can perform a retrieval request targeting that URI (a GET or HEAD request if using HTTP), which might also be redirected, and present the @@ -36,6 +35,8 @@ Except for responses to a HEAD request, the representation of a 303 response ought to contain a short hypertext note with a hyperlink to the same URI reference provided in the Location header field. -Source: [RFC7321 Section 6.4.4][1] +--- + +* Source: [RFC7321 Section 6.4.4][1] [1]: \ No newline at end of file diff --git a/contents/codes/304.md b/contents/codes/304.md index 88ecd14..350924c 100644 --- a/contents/codes/304.md +++ b/contents/codes/304.md @@ -6,18 +6,18 @@ references: "Rails HTTP Status Symbol": ":not_modified" --- -The 304 Not Modified status code indicates that a conditional GET or HEAD -request has been received and would have resulted in a [200 (OK)](/200) response -if it were not for the fact that the condition evaluated to false. +A conditional GET or HEAD request has been received and would have resulted in a +[200 OK](/200) response if it were not for the fact that the condition evaluated +to false. In other words, there is no need for the server to transfer a representation of the target resource because the request indicates that the client, which made the request conditional, already has a valid representation; the server is therefore redirecting the client to make use of that stored representation as if -it were the payload of a [200 (OK)](/200) response. +it were the payload of a [200 OK](/200) response. The server generating a 304 response MUST generate any of the following header -fields that would have been sent in a [200 (OK)](/200) response to the same +fields that would have been sent in a [200 OK](/200) response to the same request: Cache-Control, Content-Location, Date, ETag, Expires, and Vary. Since the goal of a 304 response is to minimize information transfer when the @@ -35,7 +35,9 @@ client. A 304 response cannot contain a message-body; it is always terminated by the first empty line after the header fields. -Source: [RFC7232 Section 4.1][1] +--- + +* Source: [RFC7232 Section 4.1][1] [1]: [2]: \ No newline at end of file diff --git a/contents/codes/305.md b/contents/codes/305.md index 33bde53..d079229 100644 --- a/contents/codes/305.md +++ b/contents/codes/305.md @@ -7,10 +7,11 @@ title: Use Proxy # - Due to deprecation we won't show this... but should we? --- -The 305 Use Proxy status code was defined in a previous version of this -specification and is now deprecated, due to security concerns regarding in-band -configuration of a proxy. +Defined in a previous version of this specification and is now deprecated, due +to security concerns regarding in-band configuration of a proxy. -Source: [RFC7231 Section 6.4.5][1] +--- + +* Source: [RFC7231 Section 6.4.5][1] [1]: \ No newline at end of file diff --git a/contents/codes/307.md b/contents/codes/307.md index 36be560..5eb5dfa 100644 --- a/contents/codes/307.md +++ b/contents/codes/307.md @@ -6,24 +6,26 @@ references: "Rails HTTP Status Symbol": ":temporary_redirect" --- -The 307 Temporary Redirect status code indicates that the target resource -resides temporarily under a different URI and the user agent MUST NOT change the -request method if it performs an automatic redirection to that URI. +The target resource resides temporarily under a different URI and the user agent +MUST NOT change the request method if it performs an automatic redirection to +that URI. Since the redirection can change over time, the client ought to continue using the original effective request URI for future requests. The server SHOULD generate a Location header field in the response containing a -URI reference for the different URI. The user agent MAY use the Location field +URI reference for the different URI. The user agent MAY use the Location field value for automatic redirection. The server's response payload usually contains a short hypertext note with a hyperlink to the different URI(s). -Note: This status code is similar to 302 (Found), except that it does not allow +Note: This status code is similar to 302 Found, except that it does not allow changing the request method from POST to GET. This specification defines no -equivalent counterpart for [301 (Moved Permanently)](/301) ([RFC7238][2], however, -defines the status code [308 (Permanent Redirect)](/308) for this purpose). +equivalent counterpart for [301 Moved Permanently](/301) ([RFC7238][2], however, +proposes defining the status code [308 Permanent Redirect](/308) for this purpose). -Source: [RFC7231 Section 6.4.7][1] +--- + +* Source: [RFC7231 Section 6.4.7][1] [1]: [2]: \ No newline at end of file diff --git a/contents/codes/308.md b/contents/codes/308.md index d39ee03..6a9f165 100644 --- a/contents/codes/308.md +++ b/contents/codes/308.md @@ -4,31 +4,36 @@ code: 308 title: Permanent Redirect --- -The 308 Permanent Redirect status code indicates that the target resource has -been assigned a new permanent URI and any future references to this resource -ought to use one of the enclosed URIs. +The target resource has been assigned a new permanent URI and any future +references to this resource ought to use one of the enclosed URIs. Clients with link editing capabilities ought to automatically re-link references -to the effective request URI ([Section 5.5 of RFC7230][2]) to one or more of the -new references sent by the server, where possible. +to the effective request URI[1](#ref-1) to one or more of the new +references sent by the server, where possible. -The server SHOULD generate a Location header field -([[RFC7231], Section 7.1.2][3]) in the response containing a preferred URI -reference for the new permanent URI. The user agent MAY use the Location field -value for automatic redirection. The server's response payload usually contains -a short hypertext note with a hyperlink to the new URI(s). +The server SHOULD generate a Location header field[2](#ref-2) in the +response containing a preferred URI reference for the new permanent URI. The +user agent MAY use the Location field value for automatic redirection. The +server's response payload usually contains a short hypertext note with a +hyperlink to the new URI(s). A 308 response is cacheable by default; i.e., unless otherwise indicated by the -method definition or explicit cache controls ([see RFC7234, Section 4.2.2][4]). +method definition or explicit cache controls[3](#ref-3). -Note: This status code is similar to 301 (Moved Permanently) -([RFC7231, Section 6.4.2][5]), except that it does not allow changing the -request method from POST to GET. +Note: This status code is similar to [301 Moved +Permanently](/301), except that it does not allow changing the request method +from POST to GET. -Source: [RFC738 Section 3][1] +--- + +* 1 Effective Request URI +[RFC7230 Section 5.5][2] +* 2 Location [RFC7231 Section 7.1.2][3] +* 3 Calculating Heuristic Freshness +[RFC7234 Section 4.2.2][4] +* Source: [RFC738 Section 3][1] [1]: [2]: [3]: -[4]: -[5]: \ No newline at end of file +[4]: \ No newline at end of file