Apache2-API
view release on metacpan or search on metacpan
lib/Apache2/API/Status.pm view on Meta::CPAN
PUT /some//big/file.mp4 HTTP/1.1
Host: www.example.org
Content-Type: video/mp4
Content-Length: 778043392
Expect: 100-continue
If the server refused, it could return a C<413 Request Entity Too Large> or C<405 Method Not Allowed> or even C<401 Unauthorized>, or even a C<417 Expectation Failed> if it does not support this feature.
A response C<417 Expectation Failed> means the server is likely a HTTP/1.0 server or does not understand the request and the actual request must be sent, i.e. without the header field C<Expect: 100-continue>
In some REST API implementation, the server response code C<417> is used to mean the server understood the requested, but rejected it. This is a divergent use of the original purpose of this code.
=head2 HTTP_SWITCHING_PROTOCOLS (101)
See L<rfc7231, section 6.2.2|https://tools.ietf.org/html/rfc7231#section-6.2.2>
This is used to indicate that the TCP conncection is switching to a different protocol.
This is typically used for the L<WebSocket> protocol, which uses initially a HTTP handshake when establishing the connection. For example:
GET /chat HTTP/1.1
Host: server.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Origin: http://example.com
Sec-WebSocket-Protocol: chat, superchat
Sec-WebSocket-Version: 13
Then the server could reply something like:
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
Sec-WebSocket-Protocol: chat
=head2 HTTP_PROCESSING (102)
See L<rfc 2518 on WebDAV|https://tools.ietf.org/html/rfc2518>
This is returned to notify the client that the server is currently processing the request and that it is taking some time.
The server could return repeated instance of this response code until it is done processing the request and then send back the actual final response headers.
=head2 HTTP_EARLY_HINTS (103)
See L<rfc 8297 on Indicating Hints|https://tools.ietf.org/html/rfc8297>
This is a preemptive return code to notify the client to make some optimisations, while the actual final response headers are sent later. For example:
HTTP/1.1 103 Early Hints
Link: </style.css>; rel=preload; as=style
Link: </script.js>; rel=preload; as=script
then, a few seconds, or minutes later:
HTTP/1.1 200 OK
Date: Mon, 16 Apr 2022 02:15:12 GMT
Content-Length: 1234
Content-Type: text/html; charset=utf-8
Link: </style.css>; rel=preload; as=style
Link: </script.js>; rel=preload; as=script
=head2 HTTP_OK (200)
See L<rfc7231, section 6.3.1|https://datatracker.ietf.org/doc/html/rfc7231#section-6.3.1>
This is returned to inform the request has succeeded. It can also alternatively be C<204 No Content> when there is no response body.
For example:
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 184
Connection: keep-alive
Cache-Control: s-maxage=300, public, max-age=0
Content-Language: en-US
Date: Mon, 18 Apr 2022 17:37:18 GMT
ETag: "2e77ad1dc6ab0b53a2996dfd4653c1c3"
Server: Apache/2.4
Strict-Transport-Security: max-age=63072000
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Vary: Accept-Encoding,Cookie
Age: 7
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>A simple webpage</title>
</head>
<body>
<h1>Simple HTML5 webpage</h1>
<p>Hello, world!</p>
</body>
</html>
=head2 HTTP_CREATED (201)
See L<rfc7231, section 6.3.2|https://datatracker.ietf.org/doc/html/rfc7231#section-6.3.2>
This is returned to notify the related resource has been created, most likely by a C<PUT> request, such as:
PUT /some/where HTTP/1.1
Content-Type: text/html
Host: example.org
Then, the server would reply:
HTTP/1.1 201 Created
ETag: "foo-bar"
=head2 HTTP_ACCEPTED (202)
See L<rfc7231, section 6.3.3|https://tools.ietf.org/html/rfc7231#section-6.3.3>
This is returned when the web server has accepted the request, without guarantee of successful completion.
Thus, the remote service would typically send an email to inform the user of the status, or maybe provide a link in the header. For example:
POST /some/where HTTP/1.1
Content-Type: application/json
Then the server response:
HTTP/1.1 202 Accepted
Link: </some/status/1234> rel="https://example.org/status"
Content-Length: 0
=head2 HTTP_NON_AUTHORITATIVE (203)
See L<rfc 7231, section 6.3.4|https://tools.ietf.org/html/rfc7231#section-6.3.4>
This would typically be returned by an HTTP proxy after it has made some change to the content.
=head2 HTTP_NO_CONTENT (204)
L<See rfc 7231, section 6.3.5|https://tools.ietf.org/html/rfc7231#section-6.3.5>
This is returned when the request was processed successfully, but there is no body content returned.
=head2 HTTP_RESET_CONTENT (205)
L<See rfc 7231, section 6.3.6|https://tools.ietf.org/html/rfc7231#section-6.3.6>
This is to inform the client the request was successfully processed and the content should be reset, like a web form.
=head2 HTTP_PARTIAL_CONTENT (206)
See L<rfc 7233 on Range Requests|https://tools.ietf.org/html/rfc7233>
This is returned in response to a request for partial content, such as a certain number of bytes from a video. For example:
GET /video.mp4 HTTP/1.1
Range: bytes=1048576-2097152
Then, the server would reply something like:
HTTP/1.1 206 Partial Content
Content-Range: bytes 1048576-2097152/3145728
Content-Type: video/mp4
=head2 HTTP_MULTI_STATUS (207)
See L<rfc 4918 on WebDAV|https://tools.ietf.org/html/rfc4918>
This is returned predominantly under the WebDav protocol, when multiple operations occurred. For example:
HTTP/1.1 207 Multi-Status
Content-Type: application/xml; charset="utf-8"
Content-Length: 637
<d:multistatus xmlns:d="DAV:">
<d:response>
<d:href>/calendars/johndoe/home/132456762153245.ics</d:href>
<d:propstat>
<d:prop>
<d:getetag>"xxxx-xxx"</d:getetag>
</d:prop>
<d:status>HTTP/1.1 200 OK</d:status>
</d:propstat>
</d:response>
<d:response>
<d:href>/calendars/johndoe/home/fancy-caldav-client-1234253678.ics</d:href>
<d:propstat>
<d:prop>
<d:getetag>"5-12"</d:getetag>
</d:prop>
<d:status>HTTP/1.1 200 OK</d:status>
</d:propstat>
</d:response>
</d:multistatus>
=head2 HTTP_ALREADY_REPORTED (208)
See L<rfc 5842, section 7.1 on WebDAV bindings|https://tools.ietf.org/html/rfc5842#section-7.1>
This is returned predominantly under the WebDav protocol.
=head2 HTTP_IM_USED (226)
See L<rfc 3229 on Delta encoding|https://tools.ietf.org/html/rfc3229>
C<IM> stands for C<Instance Manipulation>.
This is an HTTP protocol extension used to indicate a diff performed and return only a fraction of the resource. This is especially true when the actual resource is large and it would be a waste of bandwidth to return the entire resource. For example...
GET /foo.html HTTP/1.1
Host: bar.example.net
If-None-Match: "123xyz"
A-IM: vcdiff, diffe, gzip
Then, the server would reply something like:
HTTP/1.1 226 IM Used
ETag: "489uhw"
IM: vcdiff
Date: Tue, 25 Nov 1997 18:30:05 GMT
Cache-Control: no-store, im, max-age=30
See also the L<HTTP range request|https://tools.ietf.org/html/rfc7233> triggering a C<206 Partial Content> response.
=head2 HTTP_MULTIPLE_CHOICES (300)
See L<rfc 7231, section 6.4.1|https://tools.ietf.org/html/rfc7231#section-6.4.1> and L<rfc 5988|https://tools.ietf.org/html/rfc5988> for the C<Link> header.
See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/300>
This is returned when there is a redirection with multiple choices possible. For example:
HTTP/1.1 300 Multiple Choices
Server: Apache/2.4
Access-Control-Allow-Headers: Content-Type,User-Agent
Access-Control-Allow-Origin: *
Link: </foo> rel="alternate"
Link: </bar> rel="alternate"
Content-Type: text/html
Location: /foo
However, because there is no standard way to have the user choose, this response code is never used.
=head2 HTTP_MOVED_PERMANENTLY (301)
See L<rfc 7231, section 6.4.2|https://tools.ietf.org/html/rfc7231#section-6.4.2>
This is returned to indicate the target resource can now be found at a different location and all pointers should be updated accordingly. For example:
HTTP/1.1 301 Moved Permanently
Server: Apache/2.4
Content-Type: text/html; charset=utf-8
Date: Mon, 18 Apr 2022 17:33:08 GMT
Location: https://example.org/some/where/else.html
Keep-Alive: timeout=15, max=98
Accept-Ranges: bytes
Via: Moz-Cache-zlb05
Connection: Keep-Alive
Content-Length: 212
<!DOCTYPE html>
<html><head>
<title>301 Moved Permanently</title>
</head><body>
<h1>Moved Permanently</h1>
<p>The document has moved <a href="https://example.org/some/where/else.html">here</a>.</p>
</body></html>
See also C<308 Permanent Redirect>
=head2 HTTP_MOVED_TEMPORARILY (302)
See L<rfc 7231, section 6.4.3|https://tools.ietf.org/html/rfc7231#section-6.4.3>
This is returned to indicate the resource was found, but somewhere else. This is to be understood as a temporary change.
The de facto standard, divergent from the original intent, is to point the client to a new location after a C<POST> request was performed. This is why the status code C<307> was created.
See also C<307 Temporary Redirect>, which more formally tells the client to reformulate their request to the new location.
See also C<303 See Other> for a formal implementation of aforementioned de facto standard, i.e. C<GET> new location after C<POST> request.
=head2 HTTP_SEE_OTHER (303)
See L<rfc 7231, section 6.4.4|https://tools.ietf.org/html/rfc7231#section-6.4.4>
This is returned to indicate the result of processing the request can be found at another location. For example, after a C<POST> request, such as:
HTTP/1.1 303 See Other
Server: Apache/2.4
Location: /worked/well
It is considered better to redirect once request has been processed rather than returning the result immediately in the response body, because in the former case, this wil register a new entry in the client history whereas with the former, this would...
=head2 HTTP_NOT_MODIFIED (304)
See L<rfc 7232, section 4.1 on Conditional Request|https://tools.ietf.org/html/rfc7232#section-4.1>
This is returned in response to a conditional C<GET> or C<POST> request with headers such as:
=over 4
=item L<If-Match|https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match>
=item L<If-None-Match|https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-None-Match>
=item L<If-Modified-Since|https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Modified-Since>
=item L<If-Unmodified-Since|https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Unmodified-Since>
=item L<If-Range|https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Range>
lib/Apache2/API/Status.pm view on Meta::CPAN
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
Later, the client would do another request, such as:
GET /foo HTTP/1.1
Accept: text/html
If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
And if nothing changed, the server would return something like this:
HTTP/1.1 304 Not Modified
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
=head2 HTTP_USE_PROXY (305)
See L<rfc 7231, section 6.4.5|https://tools.ietf.org/html/rfc7231#section-6.4.5> and the L<rfc 2616, section 10.3.6 deprecating this status code|https://tools.ietf.org/html/rfc2616#section-10.3.6>
This is returned to indicate to the client to submit the request again, using a proxy. For example:
HTTP/1.1 305 Use Proxy
Location: https://proxy.example.org:8080/
This is deprecated and is not in use.
=head2 306 Switch Proxy
This is deprecated and now a reserved status code that was L<originally designed|https://lists.w3.org/Archives/Public/ietf-http-wg-old/1997MayAug/0373.html> to indicate to the client the need to change proxy, but was deemed ultimately a security risk...
For example:
HTTP/1.1 306 Switch Proxy
Set-Proxy: SET; proxyURI="https://proxy.example.org:8080/" scope="http://", seconds=100
=head2 HTTP_TEMPORARY_REDIRECT (307)
See L<rfc 2731, section 6.4.7|https://tools.ietf.org/html/rfc7231#section-6.4.7>
This is returned to indicate the client to perform the request again at a different location. The difference with status code C<302> is that the client would redirect to the new location using a C<GET> method, whereas with the status code C<307>, the...
For example:
HTTP/1.1 307 Temporary Redirect
Server: Apache/2.4
Location: https://example.org/some/where/else.html
=head2 HTTP_PERMANENT_REDIRECT (308)
See L<rfc 7538 on Permanent Redirect|https://tools.ietf.org/html/rfc7538>
Similar to the status code C<307> and C<302>, the status code C<308> indicates to the client to perform the request again at a different location and that the location has changed permanently. This echoes the status code C<301>, except that the stand...
For example:
GET / HTTP/1.1
Host: example.org
Then, the server would respond something like:
HTTP/1.1 308 Permanent Redirect
Server: Apache/2.4
Content-Type: text/html; charset=UTF-8
Location: https://example.org/some/where/else.html
Content-Length: 393
<!DOCTYPE HTML>
<html>
<head>
<title>Permanent Redirect</title>
<meta http-equiv="refresh"
content="0; url=https://example.org/some/where/else.html">
</head>
<body>
<p>
The document has been moved to
<a href="https://example.org/some/where/else.html"
>https://example.org/some/where/else.html</a>.
</p>
</body>
</html>
=head2 HTTP_BAD_REQUEST (400)
See L<rfc 7231, section 6.5.1|https://tools.ietf.org/html/rfc7231#section-6.5.1>
This is returned to indicate the client made a request the server could not interpret.
This is generally used as a fallback client-error code when other mode detailed C<4xx> code are not suitable.
=head2 HTTP_UNAUTHORIZED (401)
See L<rfc 7235, section 3.1 on Authentication|https://tools.ietf.org/html/rfc7235#section-3.1>
See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401>
This is returned to indicate to the client it must authenticate first before issuing the request.
See also status code C<403 Forbidden> when client is outright forbidden from accessing the resource.
For example:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic; realm="Secured area"
or, for APIs:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
or, combining both:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic; realm="Dev zone", Bearer
which equates to:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic; realm="Dev zone"
WWW-Authenticate: Bearer
So, for example, a user C<aladdin> with password C<opensesame> would result in the following request:
( run in 0.593 second using v1.01-cache-2.11-cpan-13bb782fe5a )