Web Information¶
Sources: [MDNHTTP], [RFC9110], [RFC9111]
Alright, let’s talk about the interweb. Given that most people seeing this and who are interested in creating an API client will likely already have some knowledge of most of these things, feel free to skip over it. However, this page is intended as a comprehensive primer for people of all experience levels into generalized internet infrastructure.
These sections include:
Terminology¶
Before getting into that, it is important to clarify some terminology that will be used throughout the document:
Term |
Definition |
|---|---|
Cache |
An HTTP “cache” is a local storage of responses that a client will control storage, retrieval, and deletion of data in. Cached data is used to reduce response times and network bandwidth consumption. |
Client |
Some entity that is sending a request to a server. |
Cookie |
An HTTP cookie is a small block of data created by a web server that is left on the client’s side after a request is made. These cookies allow server to store client/user specific data on the individual client’s end, and keep track of the state of the session. This can include staying logged in to a website, saving items in a shopping cart, and much more. |
Header |
A header is a field in an HTTP request that passes additional context about the request, e.g. media formats, operating system, authorization, and just about anything else. Additionally, a response sent to a request will also include headers from the server. |
HTTP |
The The HTTP, or Hypertext Transfer Protocol, is an application-level protocol for information systems. The modern HTTP forms the foundation for nearly the entirety of the average users’ web experience. This is why you will see many website URLs starting with |
Proxy |
A server which provides a gateway between a user/client and the end-server. The client sends requests to the proxy, which forwards them to the end server, and then returns the response back to the client. |
Request |
An HTTP request that is sent from a client, to a server, expecting some form or response/action to be taken upon being received. |
Resource |
The target of an HTTP request is called a resource. This is not limited in any way as to what this resource might be, HTTP merely defines an interaction method for the client to access this resource. |
Response |
A message send from a server, to a client, in response to a received request. This will always include a status code, and usually come content besides that. |
Server |
An entity which can receive requests from a client, and execute some action or send some response (or both) as a result. |
URI |
A URI, or Uniform Resource Identifier, is a unique sequence of characters that defines how to navigate to a web resource. These can include URLs and URNs. |
URL |
A URL, or Uniform Resource Locator, is a type of URI that specifically provides a location on a network and a mechanism for retrieving data from that location. |
URN |
A URN, or Uniform Resource Name, is a type of URI that is a template for parsers to use to find an item. This can be a server namespace and other routing information, but does not inherently give access to any data. |
User Agent |
A |
WebSocket |
An interactive connection that makes consistent two-way communication between a client and a server possible. |
HTTP Request Methods¶
When an HTTP request is made, the first piece of information any server or request-builder will ask you for is the method. This request method is used as a primary source of how to treat the request. It directly tells the server what the intention of the client is, and what the server should send to the client as a result. There are currently 9 major request methods, which are as follows:
Method |
Description |
|---|---|
The primary method for information retrieval, |
|
Identical to the GET method, except the server does not send content. This is used primarily for obtaining metadata and resource content types. |
|
The primary method for giving data to a server. This method requests that the resource processes the request information, and will often send nothing other than a confirmation in response. |
|
Requests that the target resource is either created or replaced by the data defined by the request. |
|
Requests that the server remove the data at the targeted location specified by the request. |
|
Requests that the targeted server further connect to another resource defined by the request, and then act purely as transport for data between the original client and the end server. |
|
Requests information about communication options for the target resource. |
|
Intended largely for gathering testing or diagnostic information, the |
|
Similarly to a PUT request, a |
GET¶
The GET request method is intended for information retrieval. This method is far and away the most common request
type that most developers will deal with, especilly those building an application on top of an existing API structure.
But even out outside of developers, there are GET requests everywhere. Every time you open a web page in your
browser? That’s a GET request that your browser makes to the resource at the URL you entered, and the HTML
document that gets displayed is the response to that request.
In many ways, GET requests can be looked at as database queries. A set of criteria, parameters even, are often
provided to the resource, and the resource takes those criteria and returns a response containing the relevant
information.
HEAD¶
The HEAD request method is identical to the GET method, except the server will not send any content in the
response. The head method is used for a client to obtain metadata about a resource, rather than directly obtaining
the resource itself.
The response from the server should include all of the headers that the GET request would, but simply without the content itself. However, some headers that are dependent on being set when the content is generated for the response may not be set, so this is not a guarantee.
POST¶
The POST request method requests that the targeted resource processes the data enclosed in the request according to
that resource’s implementation. Some common examples of post requests are:
Submitting a form on a website.
Posting a message on a forum.
Creating a new resource.
Adding data to a resource.
Note
If a resource is created as a result of a POST request, it should return a 201 Created status code. POST requests
may return some form of confirmation response, or sometimes include a redirection to the location of a resource where
the POST data can be found.
PUT¶
The PUT request method requests that the state of the target resource be created or replaced with the data defined
in the request. A successful PUT request usually means that a followup GET request would result in an
equivalent data to the PUT request being returned.
If a PUT request creates a resource on the server, the server will return a 201 Created status code. Otherwise, if
the PUT request updates a resource, the server should send a 200 OK or a 201 Created status code.
A server which receives a PUT request should validate the enclosed data according to its own methods before
accepting the request.
DELETE¶
The DELETE method requests that the origin server remove a target resource from its functionality. The goal is that
the endpoint specified will delete the resource. For example, if an API request targets an image library website,
a DELETE request may request the deletion of a specific image.
CONNECT¶
The CONNECT request method requests that the recipient server establish a tunnel to the destination server.
The in-between server (a proxy server) will then server purely to facilitate communication between
the client and the server. There can be multiple proxies chained together before reaching the end server.
OPTIONS¶
The OPTIONS request method is used to get information about the general communication options available for the
target resource. This allows a client to determine what options/requirements to associate with a resource endpoint,
without actually interacting with a resource.
For example, an OPTIONS request to a server endpoint might return a specific header allow, which has a value
of GET, HEAD, OPTIONS , indicating what request methods are available.
Note
By sending an OPTIONS request to the /* resource URL, the generalized request options allowed for the server
as a whole are returned. However, since many server resources have separately configured enabled methods, this
feature should probably not be used for anything more than a ping method.
TRACE¶
The TRACE request method requests a remote loop-back of the request message. This enables a client to see what
information the server receives when the request is received. However, this has previously been used to acquire
sensitive user data, and should make sure that no private/sensitive data is conveyed in the request.
Realistically, the TRACE method should only be used for debugging/development environments, not in production.
PATCH¶
The PATCH method requests partial changes to be made to a resource. Instead of the PUT or POST methods,
where resources are created of overwritten, the PATCH method is used to modify an existing resource in-place.
This is not a very common feature, but at a general level, can be implemented similarly to PUT or POST methods.
HTTP Status Codes¶
An HTTP status code is 3-digit identifier attached to the response of any request made. Similarly to the request method, this identifier can be used to direct different actions that can be taken by the clients based on the codes of the responses received. In this 3-digit code, the first digit defines the category of the response, while the second two digits have no meaning other than to differentiate themselves from the others within that category.
Before getting into the status codes, however, here are a few terms that I will be using consistently throughout the document. These are fairly common/easy-to-understand terms, but for the sake of avoiding confusion, I will put these here anyways:
That being said, the 5 primary status code categories are as follows:
Category |
Description |
|---|---|
The request was received, and the process is continuing. |
|
The request was successfully received, understood, and accepted. |
|
Further action needs to be taken by the client in order to complete the request. |
|
The request contains bad syntax or could not be fulfilled as a result of an error on the requesting client’s side. |
|
The server failed to fulfill a request that seems to be valid. |
It is important to note that when looking at these codes, however, that their actual implementations can very heavily from server to server. Common codes like a 404 Not Found code are all relatively similar, but a 403 Forbidden error can be be caused by an endless number of things. In the end, it is up to each server individually to actually implement these codes. As such, clients like this framework will often accept all available status codes, but actually doing something with them requires separate implementation for each server.
The short version of the meaning behind this is: your client should be able to tell the difference between the status code categories (1xx, 2xx, etc.), but the nuances of each individual error code are not as important on a broad scale. Additionally, many clients will also use their own status codes outside of the accepted ones in order to internalize their own response structures.
However, as someone working with an API structure, there are in a broad sense two situations that you need to be aware of regarding the response to a request:
The request was received correctly (almost always indicated by 200 OK) and the response can be processed.
Some other status code was received, meaning that the request cannot be processed as though it were the expected response.
Keeping that in mind, if you are still interested in learning about all of the accepted HTTP status codes, I will keep a glossary of them here.
1xx Informational¶
Alright, getting started, we have the category of status codes you will likely see the least: the 1xx informational
codes. There are only two standardized codes in this category, and they are interim codes. What this means is that these
codes will never be the end result of a request, but rather just a, well, informational piece of data on the status of
the request while it continues to be processed. Most of the time, these codes get handled behind the scenes while
end-users and high-level developers never touch them.
100 Continue¶
The 100 status code is sent when the initial part of a request has been received, and it has not been rejected by the
server. The server intends to respond to the request after fully receiving the request and acting on it. This is an
interim status code that conveys the server’s intentions to the client.
When the client makes their request, they might also include an Expect header in the request. When this header
is sent, and the value is set to 100-continue, the server can then send a response with the 100 status code to indicate
that it has acknowledged the intent of the client to send the request, and is willing to accept it. When the client
receives a 100 status code response after sending a request with an Expect header, the client should continue
sending the main body of the request and discard the 100 response.
Tip
If the request that the client sent did not include the Expect header, then any 100 status code responses can
simply be discarded.
101 Switching Protocols¶
The 101 status code indicates that the server understands and is willing to respond to the
client’s request. It does this via a header in the 101
response, the Upgrade header. This header carries information on what protocol the server intends
to switch to.
2xx Successful¶
The 2xx class of status codes indicate that the client’s request was successfully received by the server,
understood, and also accepted. In short, a 2xx response means that the request was valid.
200 OK¶
The 200 status code indicates that the request has succeeded. The response information contained in a 200
response often depends on the method being used. Here are some examples of what a 200 code might refer to:
201 Created¶
The 201 status code indicates that the request has been fulfilled and resulted in at least one new resource
being created. The 201 response’s content usually described how to target these new resource(s).
202 Accepted¶
The 202 status code indicates that the request has been received, but the processing has not been completed.
This can be useful for long processing of data, as this simply informs the client that the response is being worked on.
204 No Content¶
The 204 status code indicates that the server has successfully filled the request and there is no additional
content to send in the response content. This serves as a confirmation of success to the user without actually sending
any proper data in return.
205 Reset Content¶
The 205 status code indicates that the server has fulfilled the request and desires that the user reset the
“document view” to its original state. This can be received, for example, in response to submitting a form
where the user might want to enter another item into the form. Upon receiving the 205 response, the client would
reset the form fields to their defaults without needing to process any data from the response.
Note
A 205 response will not contain any content.
206 Partial Content¶
The 206 status code indicates that the server is sending a partial amount of data as a response to a request.
This is usually in relation to range requests, where something like a large file is passed to the client in smaller
chunks over separate requests instead of a single request that may timeout/drop the connection.
3xx Redirect¶
The 3xx class of status codes indicate that further action is needed from the client in order to fulfill the
request. There are 4 main types of redirections:
Redirections that indicate that the resource has been moved to a different location (e.g. 301 Moved Permanently, 307 Temporary Redirect).
Redirections that offer a choice among multiple options capable of representing the resource (e.g. 300 Multiple Choices).
Redirection to a different resource (e.g. 303 See Other).
Redirection to a previously cached result (e.g. 304 Not Modified).
For some redirect responses, the client may automatically redirect the request to the provided URI referenced in the redirect response. However, this should be done with care, and only for requests that are known to be safe, as the user may not want to redirect an unsafe request.
300 Multiple Choices¶
The 300 status code indicates that the target resource has more than one endpoint to access it from.
In ths case, the server should provide the alternate URIs to target the resource from so that the client/user can select
one.
Note
If any of these choices are preferred over the others by the server, the response should include a Location header
which contains the URL for the preferred choice.
301 Moved Permanently¶
The 301 status code indicates that the target resource has been assigned a new URI permanently, and the request
should be re-issued to a new permanent URI. The response should include a Location header which contains the new
preferred URL for the resource.
302 Found¶
The 302 status code indicates that the target resource is temporarily found under a different URI. However, since
the location of the target resource is only temporarily moved, the requests should continue to be sent to the current
URI for future requests. This should include a Location header in the response with a new URI to direct the request
to.
Note
This is highly similar to 307 Temporary Redirect, the only different really being in come client implementations.
303 See Other¶
The 303 status code inficates that the server is redirecting the user to a different resource from the one
requested, indicated by a URL in the Location header. This is intended to redirect a client to interact with a
a separate URL.
304 Not Modified¶
The 304 status code indicates that a conditional GET or HEAD request was received, and would have
returned a 200 OK response if not for the condition evaluating to False. This means that the server has no need
to transfer the resource, because the client can use the cached data instead.
Note
See [RFC9111] for information on HTTP caching.
305 Use Proxy¶
The 305 status code has been deprecated in a previous HTTP version and is no longer used.
306 (Unused)¶
The 306 status code was previously removed, and is no longer used. However, the response code is still reserved.
307 Temporary Redirect¶
The 307 status code indicates that the target resource is temporarily found under a different URI. However, since
the location of the target resource is only temporarily moved, the requests should continue to be sent to the current
URI for future requests. This should include a Location header in the response with a new URI to direct the request
to.
Note
This is highly similar to 302 Found, the only different really being in come client implementations.
308 Permanent Redirect¶
The 308 status code indicates that the target resource has been assigned a new permanent URI. This means that the
current, and any future requests, should be directed to the URI enclosed in the Location header, which should be
provided.
4xx Client Error¶
[RFC9110.15.5] [MDN Statuses Client Error]
The 4xx class of status code indicates that the client has made some form of mistake with the request. Unless the
request uses the HEAD method, the server should return content which describes how the client has erred.
400 Bad Request¶
The 400 status code is used to indicate that the server cannot or will not process the request due to an improper
request. This can be caused by a large variety of things, but some common errors include syntax errors, invalid request
structure, or untrusted request routing.
402 Payment Required¶
The 402 status code is not currently used, but is reserved for future use.
403 Forbidden¶
The 403 status code indicates that the server understood the request but refuses to fulfill it. The server may share
why that request was refused, but also may not. If the Authorization header was passed with this request, the server
has decided that the credentials provided were valid, but insufficient for accessing the requested resource.
404 Not Found¶
The 404 status code indicates that either the server did not find a resource at the requested target location, or
the server is refusing to disclose that that endpoint exists. This status code does not indicate whether the not found
status is temporary or permanent.
405 Method Not Allowed¶
The 405 status code indicates that the attempted request method is known by the server, but is not allowed/supported
for the target resource. The response should include an Allow header which specifies what request methods are
allowed.
406 Not Acceptable¶
The 406 status code indicates that the target location does not have a resource that is acceptable to the client,
according to the proactive negotiation [RFC9110.12.1] header field. This is a fairly unlikely
response code, given that proactive negotiation can be very inconsistent and is not highly recommended.
407 Proxy Authentication Required¶
The 407 status code is similar to 401 Unauthorized, except it indicates that the client needs to authenticate itself in
order to use a proxy for the request.
408 Request Timeout¶
The 408 status code indicates that the server did not receive the full request from the client in a time it was
willing to wait for.
409 Conflict¶
The 409 status code indicates that the request could not be completed due to a conflict with the state of the target
resource. This code is used in situations where the client/user can somehow resolve said conflict and resend the
request. For example, if a PUT request is changing a resource that override changes previously made by another
external user, the 409 response code might indicate that the request cannot be completed.
410 Gone¶
The 410 status code indicates that access to the target resource is no longer available at the target server, and
that this is a permanent condition. If the permanence of the target resource availability is not known, or is not
permanent, a 404 Not Found error will be used instead.
411 Length Required¶
The 411 status code indicates that the server refuses to accept the request without a defined Content-Length
header.
412 Precondition Failed¶
The 412 status code indicates that one or more conditions given in the request headers evaluated to False on the
server side. This response allows the client to apply pre-conditions to accessing a resource, and prevent the request
from being executed if the target resource is in an unexpected state.
413 Content Too Large¶
The 413 status code indicates that the server is refusing to process a request because the content is larger than
the server will process.
414 URI Too Long¶
The 414 status code indicates that the server is refusing the request because the target URI is longer than the
server will allow. This is a very rare status code that is only likely if a client converts a POST request
to a GET request accidentally, resulting in an infinite redirection.
415 Unsupported Media Type¶
The 415 status code indicates the origin server is refusing to accept the request because the content type is not
in a format supported by the resource. This is usually due to a mistake in the Content-Type or Content-Encoding
headers. The response may also include a Accept-Encoding or Accept header to specify what valid options are.
416 Range Not Satisfiable¶
The 416 status code indicates that the set of ranges in the Range header field have been rejected.
417 Expectation Failed¶
The 417 status code indicates that the expectation given in the Expect header field could not be met.
418 (Unused)¶
Now unused, the 418 status code was originally created/reserved as an April Fools joke.
421 Misdirected Request¶
The 421 status code indicates that the request was directed at a server that is unable to produce a response for the
target URI. An server might return a 421 status code for a request that has an invalid origin URI.
422 Unprocessable Content¶
The 422 status code indicates that the server understands the content type of the request, and the syntax of the
request is correct, but it was unable to process the contained data. This might include a JSON request body which
is valid syntactically, but contains invalid/missing fields.
424 Object Required¶
[MS object-required-error-424]
The 424 status code indicates that the provided object data in the request are invalid for the resource requested.
This might be a result of no providing and object, providing an object that isn’t recognized, or providing an invalid
object altogether.
425 Too Early¶
The 425 status code indicates that the server is unwilling to risk processing a request which might be replayed,
which has a potential for a replay attack.
426 Upgrade Required¶
The 426 status code indicates that the server refused to perform the request using the current protocol, but might
be willing to do so after the client switches to a different protocol. The server will provide an Upgrade header
in the response to indicate the required protocols.
428 Precondition Required¶
The 428 status code indicates that the server requires the request to be conditional. This usually means that a
required precondition header is missing, like If-Match.
Note
When a precondition does not match the server-side accepted conditions, a 412 Precondition Failed error should be raised. The
428 code is reserved for a missing precondition.
429 Too Many Requests¶
The 429 status code indicates that the user has sent too many requests in a given amount of time. This is commonly
referred to as hitting a “rate limit”.
Note
A 429 response may include a Retry-After header which indicates how long to wait before retrying the
request.
431 Request header Fields Too Large¶
The 431 status code indicates that the server will not process the request because the requests headers are too
long. This can refer to both the entirety of the headers being too long, or the length of an individual header
being too long.
Note
Servers should implement some sort of content in a 431 response that explains how or what headers are too large.
However, some common occurrences are if:
The
RefererURL header is too long.There are too many cookies in the request.
5xx Server Error¶
[RFC9110.15.6] [MDN Statuses Server Error]
The 5xx class of status codes refer to errors that occur on the side of the server. The server should include
some information about the error in the response content, unless the request is made with the GET method, in
which case no content will be sent.
500 Internal Server Error¶
The 500 status code indicates that the server encounter an unexpected error preventing it from completing the
request. This is a very broad error case.
501 Not Implemented¶
The 501 status code indicates that the server does not support the requirements for fulfilling a request.
502 Bad Gateway¶
The 502 status code indicates that the server received an invalid response from an inbound server it accessed
while attempting to fulfill the request. This often occurs in the case of a proxy server receiving an invalid
response.
504 Gateway Timeout¶
The 504 status code indicates that the server did not receive a response, within the time it was willing to wait,
from another server.
505 HTTP Version Not Supported¶
The 505 status code indicates that the server does not support the major HTTP version that the request was made
with.
506 Variant Also Negotiates¶
Honestly, I don’t know how to explain this one and I have never seen it before. Take a look at the source link here if you want to learn more.
507 Insufficient Storage¶
Status code 507 indicates that the request could not be completed because the server could not store the data needed
to complete the request.
508 Loop Detected¶
The 508 status code indicates that the server terminated an operation because it encountered an infinite loop while
processing a request.
510 Not Extended¶
The 510 status code indicates that the server could not use a specified extension that the client’s request
incorporated.
511 Network Authentication Required¶
The 511 status code indicates that the client needs to authenticate to gain network access. This status is generated
by proxies that control access to a network rather than the network server itself.
Reference¶
- MDNHTTP
HTTP | MDN. (2022, May 13). MDN Web Docs. Retrieved June 13, 2022, from https://developer.mozilla.org/en-US/docs/Web/HTTP .
- RFC9110
Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., “HTTP Semantics”, STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022, https://datatracker.ietf.org/doc/html/rfc9110 .
- RFC9111
Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., “HTTP Caching”, STD 98, RFC 9111, DOI 10.17487/RFC9111, June 2022, https://www.rfc-editor.org/info/rfc9111 .