HTTP Verbs Simplified

Cross-posted from : https://www.andeshchogle.com/blog/post/http-verbs-simplified/

WHAT IS A URL (OR A URI)

URL, or Uniform Resource Locator (URI, or Uniform Resource Identifier) is a way to locate a resource on a network.

For example:

http://www.contoso.com/users/1

We could explain the above URL as: it identifies a user with “Id” of 1, present in “users” collection on the network pointed to by “www.contoso.com” and can be accessed over “http” protocol.

Example 2:

http://www.contoso.com/users

The above URL identifies a “users” collection on the network pointed to by “www.contoso.com” and can be accessed over “http” protocol.

THE PART THAT HTTP PLAYS

Now that we have located a resource using a URL, we can do various things to it using HTTP as our protocol of “doing various things to that resource”. HTTP standard has some predefined “verbs” (or actions) that we can use. Each of these verbs has a predefined behavior in terms of:

1. What input is required to use that verb (i.e. to carry out that action)
2. What should we expect in return when that action is executed
3. What happens if we execute that same verb more than once on the same resource
4. What happens if the URL is wrong, i.e. if the URL is pointing to a non-existent resource

What follows is a list of most commonly used HTTP Verbs and their behavior.

GET

As the name suggests, executing GET on a URL gets you the resource pointed by that URL. The response of executing GET will usually have a status code of 200 (i.e. “OK”, i.e. the request was successfully executed), and the body of that response will be the actual resource.

GET /users/1

In the above example, we will get a user with id 1 form the “users” collection.

If the user with id 1 does not exist, or if the users collection itself does not exist, the request will return with a status code 404 (Not Found).

By standard, a GET request is idempotent. In simple terms, this means that from a server’s perspective, executing the the request more than once will have the same effect as executing the request just once. For example, if we execute the same GET request more than once, the server should remain in the same state as if the request is executed just once.

POST

POST /users
 
{
    id: 1,
    firstName: "John",
    lastName: "Doe",
    age: 30,
    profilePic: "http://www.contoso.com/media/johndoe.jpg",
    address: {
        city: "Pune",
        state: "Maharashtra",
        country: "India"
    }
}

In the above example we are executing a POST against the URL “/users”. The request body contains a representation of a user in JSON format. In this example, we are saying to the server, “accept this resource as a user under the /users collection”. Depending on the business logic, the server may then create a user object under “users” collection, or do some similar thing.

If the server creates the user, it should return a 201 (Created) status code. If the server chooses to do something else with the posted user then it may return 200 (OK) status code.

The POST request is neither required nor expected to be idempotent. This means that if we execute a POST request more than once, each request will have its own effect on the server. From server’s perspective, executing it more than once is not the same as executing it just once. In case of the the above POST request, executing it once creates a user, executing it twice will create a duplicate user.

PUT

PUT /users/1
 
{
    id: 1,
    firstName: "John",
    lastName: "Doe",
    age: 30,
    profilePic: "http://www.contoso.com/media/johndoe.jpg",
    address: {
        city: "Pune",
        state: "Maharashtra",
        country: "India"
    }
}

In the above PUT request, we are saying to the server, “take this user resource and put it at the /users/1 location”.

The server is expected to put the supplied resource at “/users/1” location. If a resource is already present at the “/users/1” location, the server is expected to consider the supplied user resource as the updated version of the resource and replace the old one with the new one.

If the request results in the server creating the new resource, the server should respond with a 201 (Created) status code. If the request results in updating the existing resource, the server may reply with a 200 (OK) status code.

The PUT request is expected to be idempotent by the standard. This means that executing the same PUT request multiple times will leave the server in the same state as executing it just once – i.e. with just one user located at /users/1

DELETE

DELETE /users/1

Simply stated, a DELETE will request the server to delete the resource present at the specified location. In the above example, the DELETE request will delete the user located at /users/1

The server should respond with a 200 (OK) status code if it deletes the resource, or 202 (Accepted), if it has accepted the request and has not deleted the resource yet, but will delete it later.

The DELETE is also expected to be idempotent. So, executing the DELETE request “DELETE /users/1” more than once will leave the server in the same state as executing “DELETE /users/1” just once – that is, with no user at /users/1 location.

There are other verbs too such as HEAD, OPTIONS, PATCH, etc., but the above ones are the four most commonly used.

This article is simplified for better understandability. The most authentic place to learn about these verbs is the World Wide Web Consortium (W3C) website itself. So for deep diving into the subject, you may want to head over to http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html

REFERENCES

RFC 2616, Section 9: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html