HTTP Request Methods
This article is a quick reference for HTTP request methods. If you’re just looking for a specific method, jump here.
Background
HTTP is a stateless, application-layer protocol for communications on the Web. Text, images, and other forms of hypermedia are served over HTTP to web browsers. The protocol defines request methods to facilitate client-server interactions through requests and responses. These methods are defined in RFC 7231 and are the topic of this article.
Definitions
Safe
Safe methods are not intended to make changes to the target resource (i.e. they have no side effects). Note that this is only semantics with regards to the request, so the server’s response may still have side effects. The requester, however, cannot be held responsible for any additional, resulting behavior by the server. (MDN Doc)
Idempotent
Idempotent methods can be applied in multiple, sequential requests with the same effect on the target resource as a single request of that same method. Additional, sequential requests to an idempotent method may return differing status codes, but the target resource will remain unchanged from the initial request. All safe methods are also idempotent. (MDN Doc)
Two things to note: 1) the word sequential and 2) the responsibility of this method.
To the first note: if a separate request was made between two requests to an idempotent method (thus the sequence was broken), then the idempotent quality of the method no longer holds.
To the second note: the responsibility of idempotence rests on the server, not the client. The server should implement methods correctly to maintain the idempotent constraint, though this is not guaranteed.
Cacheable
Cacheable methods can be cached (i.e. stored) by the client for later reuse. The HTTP spec notes that “In general, safe methods that do not depend on a current or authoritative response are defined as cacheable.” (MDN Doc)
GET and HEAD methods are cacheable. POST and PATCH methods can be as well, though this is uncommon. To be cacheable, the method response should contain a cacheable status code and specific headers.
Methods
Methods as described in short by RFC 7231:
╔═════════╦═════════════════════════════════════════════╗
║ Method ║ Description ║
╠═════════╬═════════════════════════════════════════════╣
║ GET ║ Transfer a current representation of the ║
║ ║ target resource. ║
║ HEAD ║ Same as GET, but only transfer the status ║
║ ║ line and header section. ║
║ POST ║ Perform resource-specific processing on the ║
║ ║ request payload. ║
║ PUT ║ Replace all current representations of the ║
║ ║ target resource with the request payload. ║
║ DELETE ║ Remove all current representations of the ║
║ ║ target resource. ║
║ CONNECT ║ Establish a tunnel to the server identified ║
║ ║ by the target resource. ║
║ OPTIONS ║ Describe the communication options for the ║
║ ║ target resource. ║
║ TRACE ║ Perform a message loop-back test along the ║
║ ║ path to the target resource. ║
╚═════════╩═════════════════════════════════════════════╝GET
A GET method is used to request a targeted resource from a server. This is the primary method for information retrieval. (MDN Doc)
Example: GET /posts/{blog} : returns a list of all posts from the specified blog
GET method details:
╔═══════════════╦═════╗
║ Request Body ║ No ║
║ Response Body ║ Yes ║
║ Safe ║ Yes ║
║ Idempotent ║ Yes ║
║ Cacheable ║ Yes ║
╚═══════════════╩═════╝Note: GET method requests do not have a body. To specify request parameters (as in the example above), query strings can be used.
HEAD
A HEAD method is identical to a GET method, except the response does not contain a body. The response header should be no different to that of a GET method for the same request. HEAD request methods are commonly used to receive metadata. (MDN Doc)
HEAD method details:
╔═══════════════╦═════╗
║ Request Body ║ No ║
║ Response Body ║ No ║
║ Safe ║ Yes ║
║ Idempotent ║ Yes ║
║ Cacheable ║ Yes ║
╚═══════════════╩═════╝POST
A POST method is used to send data to a server. In HTTP spec terms, it “requests that the target resource process the representation enclosed in the request.” (MDN Doc)
Example: POST /recipe/{list} : adds a recipe to the given list
POST method details:
╔═══════════════╦═════╗
║ Request Body ║ Yes ║
║ Response Body ║ Yes ║
║ Safe ║ No ║
║ Idempotent ║ No ║
║ Cacheable ║ No* ║
╚═══════════════╩═════╝* See Cacheable under the Some Definitions section above
Note: POST methods are not idempotent. Considering the example above, repeated requests made to /recipe/{list} may add multiple copies of the same recipe to the given list. I say may, because POST methods are not necessarily non-idempotent (i.e. they may be idempotent, but this cannot be guaranteed).
PUT
A PUT method is used to create or replace a targeted resource on a server. PUT methods are similar to POST methods, though they are idempotent. (MDN Doc)
Example: PUT /profile/photo/{user} : updates the given user’s profile photo (or uploads a new one if one doesn’t currently exist)
PUT method details:
╔═══════════════╦═════╗
║ Request Body ║ Yes ║
║ Response Body ║ No ║
║ Safe ║ No ║
║ Idempotent ║ Yes ║
║ Cacheable ║ No ║
╚═══════════════╩═════╝Consider the example used for the POST method (/recipe/{list}). If we design this in a way so only one copy of a recipe can exist in a list, then the request becomes idempotent. In this case, a PUT method could be used for the request.
Though PUT is used to create or update a whole, singular targeted resource, it may also be used for partial updates in particular instances: “Partial content updates are possible by targeting a separately identified resource with state that overlaps a portion of the larger resource.”
DELETE
A DELETE method requests that the server “remove the association between the target resource and its current functionality.” In general, this method is used to delete a targeted resource on the server, as the name implies. (MDN Doc)
Example: DELETE /video/{id} : deletes the video with the given id
DELETE method details:
╔═══════════════╦═════╗
║ Request Body ║ May ║
║ Response Body ║ May ║
║ Safe ║ No ║
║ Idempotent ║ Yes ║
║ Cacheable ║ No ║
╚═══════════════╩═════╝CONNECT
A CONNECT method is used to establish a two-way communications tunnel with the requested resource. It is intended only for use in connection requests to a proxy. A client sending a CONNECT method request to a server must send an authority form (see RFC 7230) request-target (i.e. the hostname followed by the port number, separated by a colon). A proxy recipient of a CONNECT method request can either establish a direct connection to the destination server or pass the connection to a subsequent proxy. (MDN Doc)
Example: CONNECT www.example.com:80 HTTP/1.1
CONNECT method details:
╔═══════════════╦═════╗
║ Request Body ║ No ║
║ Response Body ║ Yes ║
║ Safe ║ No ║
║ Idempotent ║ No ║
║ Cacheable ║ No ║
╚═══════════════╩═════╝OPTIONS
An OPTIONS method requests information about the available communication options for a targeted resource on the server. “This method allows a client to determine the options and/or requirements associated with a resource, or the capabilities of a server, without implying a resource action.” A request can specify a single resource or an asterisk (per asterisk form of the request-target; see RFC 7230) to specify the entire targeted server. (MDN Doc)
Example: OPTIONS example.com HTTP/1.1 -or- OPTIONS * HTTP/1.1
OPTIONS method details:
╔═══════════════╦═════╗
║ Request Body ║ No ║
║ Response Body ║ Yes ║
║ Safe ║ Yes ║
║ Idempotent ║ Yes ║
║ Cacheable ║ No ║
╚═══════════════╩═════╝TRACE
A TRACE method requests an application-level loopback with the (mostly identical) request method received by the targeted server. By loopback, this means the final destination of the request is the client/origin (or as noted by RFC 7231, the first server to receive a Max-Forwards value of 0 in the request header). This method request type is useful for debugging purposes. (MDN Doc)
Example: TRACE /index.html
TRACE method details:
╔═══════════════╦═════╗
║ Request Body ║ No ║
║ Response Body ║ No ║
║ Safe ║ Yes ║
║ Idempotent ║ Yes ║
║ Cacheable ║ No ║
╚═══════════════╩═════╝Additional Methods
PATCH
Though not included in RFC 7231, this method is separately specified in RFC 5789. A PATCH method is used to make partial updates to a targeted resource. (MDN Doc)
Example: PATCH /user : partially updates details for a user on a server (e.g. update name, address, etc. without modifying other existing details).
PATCH method details:
╔═══════════════╦═════╗
║ Request Body ║ Yes ║
║ Response Body ║ Yes ║
║ Safe ║ No ║
║ Idempotent ║ No ║
║ Cacheable ║ No ║
╚═══════════════╩═════╝HTTP Method Registry
The above methods are the only ones specified and defined by the HTTP spec in RFC 7231, though additional methods can be registered with the HTTP Method Registry for standardization.
Unrecognized / unsupported methods
If a request is made to your server with an unrecognized method, the response should contain a 501 Not Implemented status code. If a request is made with a recognized method though unsupported for the target resource, the response should contain a 405 Method Not Allowed status code.
Node.js and Express.js
Node supports all standard methods specified by the HTTP spec listed above, plus some additional methods found in http.METHODS:
Welcome to Node.js v14.16.0.
Type ".help" for more information.
> http.METHODS
[
'ACL', 'BIND', 'CHECKOUT',
'CONNECT', 'COPY', 'DELETE',
'GET', 'HEAD', 'LINK',
'LOCK', 'M-SEARCH', 'MERGE',
'MKACTIVITY', 'MKCALENDAR', 'MKCOL',
'MOVE', 'NOTIFY', 'OPTIONS',
'PATCH', 'POST', 'PRI',
'PROPFIND', 'PROPPATCH', 'PURGE',
'PUT', 'REBIND', 'REPORT',
'SEARCH', 'SOURCE', 'SUBSCRIBE',
'TRACE', 'UNBIND', 'UNLINK',
'UNLOCK', 'UNSUBSCRIBE'
]
>Express supports all methods listed in http.METHODS. See app.METHOD in the express API reference for details.
