9 HTTP Methods You May Want To Know

deddy

Create CRUD operations.

Photo by Caspar Camille Rubin on Unsplash

In my other article, “10 Best Practices for Naming REST API Endpoints,” I had briefly mentioned HTTP. The Hypertext Transfer Protocol, more commonly known as HTTP, is said to be a standard. It is used to communicate between clients and servers. How it works is through the request-response protocol between a client and server.

A quick example of how it works:

Imagine your browser (client) sends an HTTP request to the server (for whichever site you are trying to access). Then the server returns a response to the client. This response contains the status information about your request and may or may not contain the requested content, depending on the purpose.

As described in the quick example above, that is the request-response protocol. HTTP has methods or verbs, such as the commonly used ones POST, GET, PUT, DELETE. These four correspond to create, read, update, and delete (CRUD) operations respectively. As I said, these are only some of the commonly used available methods, so that means there are a number of other methods that are utilized less frequently. You might see a few more of them as you read on.

Here are the methods that I am going to talk about:

  1. GET
  2. POST
  3. PUT
  4. DELETE
  5. HEAD
  6. PATCH
  7. OPTIONS
  8. CONNECT
  9. TRACE

Their names are also case sensitive and must be used in uppercase. (I personally think this is an overlooked fun fact.)

Before we jump into the details of each, one thing to know is that some methods, like GET and HEAD, are conventionally made to only have the function of retrieval and nothing else. As such, they are also considered safe.

Also because of the convention, other methods, like POST, PUT, and DELETE, are possibly unsafe actions.

Other than the safe-unsafe property, methods also have the property of idempotence. Simply put, when a method is applied, it is deemed to be idempotent when no matter how many times it is applied, the result does not change beyond its initial application.

Methods like GET, HEAD, PUT, and DELETE always return the same one result expectedly, and hence they are inherently idempotent. This is true provided that no concurrent operations are being executed on the same set of resources, of course. Else, the result should not have deviated from its original application.

Now you know about the two properties, let’s take a look deeper into each method.

1. GET

GET is the most common and widely used method in APIs and websites. Whenever you try to access a website, which is basically an act of requesting data or retrieval of data from a specified resource or server, you are calling this method.

Since this is only retrieving data, it should not have any other effect on the data or on any other data.

Here is the example of the header for GET.

Request header example:

GET /hello.html HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
Host: www.example.com
Accept-Language: en-us
Accept-Encoding: gzip, deflate
Connection: Keep-Alive

Response header example:

HTTP/1.1 200 OK
Server: Apache/2.2.14 (Win32)
ETag: "34aa387-d-1568eb00"
Vary: Authorization,Accept
Accept-Ranges: bytes
Content-Length: 88
Content-Type: text/html
Connection: Closed

Response data example:

<html>
<body>
<h1>Hello, World!</h1>
</body>
</html>

From the above examples, we can see the header when you are requesting hello.html, then the header for the response that you get back, and then the content response which will then be loaded onto your browser.

How is it done visually? It is basically calling www.example.com/hello.html on your browser URI bar.

Make sense? Remember that you use GET requests to retrieve resource representation/information only, and not to modify it in any way. Since the GET method does not change the state of the resource, it is said to be a safe method.

Additionally, GET APIs must produce the same result every time they are called, no matter how many identical requests are made. Hence, the GET method is also idempotent. This is true provided that the state of the resource has not been changed by any other modifying methods on the server.

For example, if we are calling GET http://www.example.com/customers/12345/orders multiple times, it will always return the same orders for the specific customer with ID: 12345, unless the customer has eventually changed orders somehow, and if so, from that point the result would be different.

There are also some other notes about GET:

  • GET requests can be cached.
  • GET requests remain in the browser history.
  • GET requests can be bookmarked.
  • GET requests should never be used when dealing with sensitive data.
  • GET requests have length restrictions.
  • GET requests are only used to request data (not modify).

What about the GET returns then? The return or response status should be 200 (OK), which is just like what is shown under the response header example above.

However, when there is an error, it most often returns either a 404 (NOT FOUND) or 400 (BAD REQUEST).

2. POST

The method is also quite common and widely used in APIs and websites. It is used to send data to a server and to create or update a resource.

You will most often encounter this when you are submitting a form online. Behind the scenes, it sends your data input to a server. File uploading also falls under this.

In practice, it is most often used to create new resources. That is because there is another method that is quite commonly used as well to update a resource.

POST is neither safe nor idempotent. It is not safe because it modifies data. It is also non-idempotent as the result of it being not safe. Making two identical POST requests will most likely result in two resources containing the same information. Even if it is not identical, it will result in two resources.

The examples would be as follows.

Request header example:

POST /feedback.html HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
Host: www.example.com
Content-Type: text/xml; charset=utf-8
Content-Length: 88
Accept-Language: en-us
Accept-Encoding: gzip, deflate
Connection: Keep-Alive

Request data example:

<?xml version="1.0" encoding="utf-8"?>
<string xmlns="http://clearforest.com/">string</string>

Response header example:

HTTP/1.1 200 OK
Server: Apache/2.2.14 (Win32)
ETag: "34aa387-d-1568eb00"
Vary: Authorization,Accept
Accept-Ranges: bytes
Content-Length: 88
Content-Type: text/html
Connection: Closed

Response data example:

<html>
<body>
<h1>Request Processed Successfully!</h1>
</body>
</html>

From our perspective, we are probably calling something like this: POST www.example.com/feedback.html.

For the response content, you may or may not receive it depending on the creator. However, you will still receive the response header to indicate whether it was a successful request or not.

Some other notes on the POST method:

  • POST requests are never cached.
  • POST requests do not remain in the browser history.
  • POST requests cannot be bookmarked.
  • POST requests have no restrictions on data length.

The responses to POST are also not cacheable unless the response includes appropriate cache control or Expires header fields.

For the return, it can return these three HTTP statuses:

  • 201 (Created) with a Location header with a link to the newly-created resource
  • 200 (OK), which might not result in a resource that can be identified by a URI
  • 204(No Content), which is also another one that specifically says there is no resource returned

For the error cases, it can return 404 (Not Found) or 409 (Conflict) if the resource already exists.

3. PUT

PUT is another method that is also quite common and widely used in APIs and websites. It is used to send data to a server and to create or update a resource.

However, remember that I said POST is better used for creating a resource? The PUT method is primarily used to update existing resources. If the resource to be updated does not exist, then the API may decide to create a new resource or not.

Since it modifies the state on the server, it is unsafe. However, it is idempotent. That is the difference between POST and PUT. This is because calling PUT requests multiple times will always produce the same result. In comparison, calling a POST request repeatedly has the side effect of creating the same resource multiple times.

If, for instance, calling PUT on a resource increments a counter within the resource, the call is no longer idempotent. Sometimes that happens, and it may be deemed as not idempotent. However, it is recommended to keep PUT requests idempotent and strongly recommended to use POST for non-idempotent requests.

Here are the examples for PUT.

Request header example:

PUT /hello.html HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
Host: www.example.com
Accept-Language: en-us
Connection: Keep-Alive
Content-type: text/html
Content-Length: 182

Request data example:

<html>
<body>
<h1>Hello, World!</h1>
</body>
</html>

Response header example:

HTTP/1.1 201 Created
Server: Apache/2.2.14 (Win32)
Content-type: text/html
Content-length: 30
Connection: Closed

Response data example:

<html>
<body>
<h1>The file was created.</h1>
</body>
</html>

From our perspective, the call probably is like this: PUT www.example.com/hello.html.

Just like POST, a body in the response is also optional. The PUT method is also not cacheable.

For the HTTP statuses, the user will be informed accordingly for the successful cases:

  • 201 (Created) if a resource is created
  • 200 (OK) if an existing resource is updated and possibly with a content response
  • 204 (No Content) if an existing resource is updated with no content

For error cases, you can return 404 (Not Found) if the input ID is not found or invalid. Otherwise, you can return 405 (Method Not Allowed) unless you want to update/replace every resource in the entire collection.

4. DELETE

DELETE is another method that is also quite commonly and widely used in APIs and websites. It is used to delete a specified resource.

The DELETE method is used to request the server to delete a file at a location specified by the given URL. This one is pretty straightforward.

DELETE operations are idempotent. If you DELETE a resource, it is removed. Repeatedly calling DELETE on that resource ends up the same: The resource is gone.

If calling DELETE, say, decrements a counter (within the resource), the DELETE call is no longer idempotent. This is because the data has been changed. However, you don’t usually encounter such usage of DELETE.

The following are the examples for it.

Request header example:

DELETE /hello.html HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
Host: www.example.com
Accept-Language: en-us
Connection: Keep-Alive

Response header example:

Response header example:
HTTP/1.1 200 OK
Server: Apache/2.2.14 (Win32)
Content-type: text/html
Content-length: 30
Connection: Closed

Response data example:

<html>
<body>
<h1>Resource deleted.</h1>
</body>
</html>

The call for this roughly looks like this: DELETE www.example.com/hello.html.

This method is also not cacheable.

Three possible returns for successful cases are:

  • 200 (OK) with a response body
  • 204 (No Content) with no response body
  • 202 (Accepted) if the action has been queued

However, when calling DELETE on a resource a second time, it will often return a 404 (NOT FOUND) since it was already removed and therefore is no longer findable.

For some, this makes DELETE operations no longer idempotent. However, the end state of the resource is the same.

5. HEAD

Personally I don’t usually see this method used. However, it behaves like a GET method, except that it doesn’t have the response body.

The HEAD method is functionally similar to GET, except that the server replies with no entity body (basically just header information). The server does not send any data after the header. In other words, if GET /orders returns a list of orders, then HEAD /orders will make the same request but will not return any list.

HEAD requests are useful for checking what a GET request will return before actually making a GET request — like before downloading a large file or response body.

It is also a safe and idempotent one, just like the GET method.

Here are the examples for HEAD.

Request header example:

HEAD /hello.html HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
Host: www.example.com
Accept-Language: en-us
Accept-Encoding: gzip, deflate
Connection: Keep-Alive

Response header example:

HTTP/1.1 200 OK
Server: Apache/2.2.14 (Win32)
ETag: "34aa387-d-1568eb00"
Vary: Authorization,Accept
Accept-Ranges: bytes
Content-Length: 88
Content-Type: text/html
Connection: Closed

No response data example.

For the HTTP statuses, they are pretty much the same as the ones from the GET method.

6. PATCH

This is also another one that I don’t usually see, but still it is good to know. It is used for updates as well, just like “patching” in games. However, there is a difference between this and PUT whereby PATCH is more of like update-modify while PUT is more of an update-replace kind of update.

As such, the PATCH request only needs to contain the changes to the resource, not the complete resource. It applies the differences (partial update) rather than replacing the entire resource. Meanwhile, PUT is used if you’re replacing a resource in its entirety.

PATCH is neither safe nor idempotent. However, a PATCH request can be issued in such a way as to be idempotent, which also helps to prevent bad outcomes from collisions between two PATCH requests on the same resource in a similar time frame.

For the example, let’s take a look at the data content instead for better understanding. Let’s say we have this data:

{
“name” : “Mark”,
“isUser” : false,
“numberOfDogs” : 8
}

Then we want to update it with this:

{
“numberOfDogs” : 10,
“numberOfCats” : 0
}

The outcome would be something like this:

{
“name” : “Mark”,
“isUser” : false,
“numberOfDogs” : 10,
“numberOfCats” : 0
}

Notice how it just does patching, updating the old value and adding in a new field.

For PUT, using the same existing data and input data, the output request will only contain:

{
“numberOfDogs” : 10,
“numberOfCats” : 0
}

This is because PUT is more of like update-replace while PATCH is more of like update-modify.

Sending a PATCH request on a resource that doesn’t exist will fail and no resource will be created.

Note that there are some listed challenges if you decide to use PATCH APIs in your application:

  • Support for PATCH in browsers, servers, and web application frameworks is not universal. IE8, PHP, Tomcat, Django, and lots of other software have missing or broken support for it.
  • The payload of a PATCH request is not as straightforward as it is for a PUT request.

7. OPTIONS

This one I personally only used once. It is used to request information about the communication options available. It describes the communication options for the target resource.

Basically, you can find the list of HTTP methods and other options supported by a web server on the specified URL (be it an asterisk to refer to the entire server, or a particular one just specifically pertaining to the URL).

The following example requests a list of methods supported by a web server running on host <host>:

Request header example:

OPTIONS * HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)

Response header example:

HTTP/1.1 204 No Content
Server: Apache/2.2.14 (Win32)
Allow: GET,HEAD,POST,OPTIONS
Content-Type: httpd/unix-directory

This method is safe, idempotent, and not cacheable.

8. CONNECT

This method cannot be found in Postman, if you use the tool. Its use is to establish a tunnel to the server identified by a given URI.

It is basically used by the client to establish a network connection to a web server over HTTP. That’s it.

The following example requests a connection with a web server running on the host <host>:

Request header example:

CONNECT www.example.com HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)

Response header example:

HTTP/1.1 200 Connection established
Server: Apache/2.2.14 (Win32)

The header status return is simply 200 “Connection Established”. I would say it is pretty much like OPTIONS whereby the headers appear very simple and straightforward.

9. TRACE

This method performs a message loop-back test along the path to the target resource.

Basically, it is used to echo the contents of an HTTP request back to the requester to test/debug at the time of development.

It probably looks something like the following.

Request header example:

TRACE / HTTP/1.1
Host: www.example.com
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)

Response header example:

HTTP/1.1 200 OK
Server: Apache/2.2.14 (Win32)
Connection: close
Content-Type: message/http
Content-Length: 39
TRACE / HTTP/1.1
Host: www.example.com
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)

Conclusion

When creating APIs, sometimes it is good to know about the differences of each HTTP method. This is so as to create a more accurate API with a more accurate purpose. Usually beginners tend to confuse all these, and hence they just use GET for everything, which of course can pose security issues when dealing with sensitive data, or any data. Sometimes as one progresses, one can still feel confused about certain methods, as to when to use which.

I hope you have learned a thing or two and were enlightened by reading this article. Feel free to comment or share with other people if you find this helpful.

Thanks for reading!

Related Posts