The Verbs of the Web: A Beginner's Guide to HTTP Methods (GET, POST, PUT, DELETE)

Ever wondered how your browser "tells" a website what it wants to do? Or how your favorite app manages to create new posts, update your profile, or delete old messages? It's all thanks to HTTP Methods!

Think of HTTP methods as the "verbs" or "actions" you can perform when communicating with a web server. Just like in a sentence, verbs define the action being taken. In the world of web APIs, these verbs tell the server what kind of operation you intend to perform on a specific resource (like a user, a photo, or a blog post).

Let's break down the most common and crucial HTTP methods you'll encounter, often called the CRUD operations: Create, Read, Update, and Delete.

1. GET: Just Give Me the Information! (The "Read" Action)

• What it does: When you use GET, you're essentially saying, "Hey server, please retrieve or read some data for me." You're not trying to change anything on the server; you just want to look at information.
• Analogy: Imagine you're at a library and you ask the librarian, "Can I get that book on space travel?" You're not changing the book or the library's records; you're just receiving a copy to read.
• When to use it:
  • Visiting any website (e.g., typing google.com)
  • Viewing a list of products in an online store
  • Seeing your profile page on a social media app
  • Searching for something
• Key Traits:
  • Safe: It doesn't modify the server's data.
  • Idempotent: Making the same GET request multiple times will always yield the same result (the same data).

FastAPI Example:

In FastAPI, you use @app.get() to define an endpoint that handles GET requests.

from fastapi import FastAPI

app = FastAPI()

# Imagine this is our database of books
books_db = {
    1: {"title": "The Hobbit", "author": "J.R.R. Tolkien"},
    2: {"title": "Dune", "author": "Frank Herbert"}
}

@app.get("/books/{book_id}")
async def get_book(book_id: int):
    """Retrieves a single book by its ID."""
    if book_id not in books_db:
        return {"error": "Book not found", "status_code": 404} # We'll cover HTTP exceptions later!
    return books_db[book_id]

# How to test: Open your browser to http://127.0.0.1:8000/books/1
# You'll get: {"title":"The Hobbit","author":"J.R.R. Tolkien"}

---

2. POST: Here's Some New Stuff! (The "Create" Action)

• What it does: POST is used when you want to send new data to the server to create a new resource. You're giving the server information it didn't have before.
• Analogy: This is like filling out a form to get a new library card. You're providing your details, and the library creates a brand new record for you.
• When to use it:
  • Signing up for a new account
  • Submitting a new comment or blog post
  • Adding a new item to a shopping cart
  • Uploading a photo to social media
• Key Traits:
  • Not Safe: It does change data on the server (it creates new data).
  • Not Idempotent: Sending the exact same POST request multiple times will typically create multiple new resources (e.g., submitting the same comment twice creates two comments).

FastAPI Example:

You use @app.post() for endpoints that create new data.

# main.py (continued)
# ... app = FastAPI() and books_db ...

next_book_id = 3 # Simple way to generate new IDs

@app.post("/books/")
async def create_book(title: str, author: str):
    """Creates a new book."""
    global next_book_id
    new_book = {"title": title, "author": author}
    books_db[next_book_id] = new_book
    created_id = next_book_id
    next_book_id += 1
    return {"message": "Book created!", "id": created_id, "book": new_book}

# How to test (using Postman/Insomnia):
# Method: POST
# URL: http://127.0.0.1:8000/books/
# Body (raw JSON): {"title": "The Lord of the Rings", "author": "J.R.R. Tolkien"}
# You'll get: {"message":"Book created!","id":3,"book":{"title":"The Lord of the Rings","author":"J.R.R. Tolkien"}}

3. PUT: Replace the Old with the New! (The "Update" Action - Full Replacement)

• What it does: PUT is used to completely update an existing resource. When you send a PUT request, you typically send the entire, new version of the resource. If the resource doesn't exist, PUT might create it (though POST is usually preferred for creation).
• Analogy: Imagine you tell the librarian, "Take this new edition of 'Dune' and completely replace the old one on shelf #2." The old book is gone, and the new one is exactly in its place.
• When to use it:
  • Updating all fields of a user's profile
  • Replacing a complete document or configuration file
• Key Traits:
  • Not Safe: It does change data on the server.
  • Idempotent: Sending the exact same PUT request multiple times will result in the same final state of the resource. (You replaced it once, replacing it again with the same data changes nothing further).

FastAPI Example:

Use @app.put() for full updates.

# main.py (continued)
# ... app = FastAPI() and books_db ...

@app.put("/books/{book_id}")
async def update_book(book_id: int, title: str, author: str):
    """Updates an existing book by replacing its data."""
    if book_id not in books_db:
        return {"error": "Book not found", "status_code": 404}

    books_db[book_id] = {"title": title, "author": author} # Overwrites the old data
    return {"message": f"Book {book_id} updated!", "book": books_db[book_id]}

# How to test (using Postman/Insomnia):
# Method: PUT
# URL: http://127.0.0.1:8000/books/1
# Body (raw JSON): {"title": "The Hobbit: A New Adventure", "author": "J.R.R. Tolkien (Updated)"}
# Now, if you GET http://127.0.0.1:8000/books/1, you'll see the new title and author.

4. DELETE: Make It Disappear! (The "Delete" Action)

• What it does: As the name suggests, DELETE is used to remove or delete a specific resource from the server.
• Analogy: You tell the librarian, "Please remove that damaged copy of '1984' from the collection." The book is then gone.
• When to use it:
  • Deleting a user account
  • Removing a specific product from inventory
  • Deleting a comment or photo
• Key Traits:
  • Not Safe: It does change data on the server (it removes it).
  • Idempotent: Sending the exact same DELETE request multiple times will have the same final effect. (After the first successful deletion, the resource is gone. Subsequent attempts to delete it might return a "Not Found" error, but no new changes occur).

FastAPI Example:

Use @app.delete() for deletion.

# main.py (continued)
# ... app = FastAPI() and books_db ...

@app.delete("/books/{book_id}")
async def delete_book(book_id: int):
    """Deletes a book by its ID."""
    if book_id not in books_db:
        return {"error": "Book not found", "status_code": 404}

    del books_db[book_id] # Removes the entry from our dictionary
    return {"message": f"Book {book_id} deleted successfully!"}

# How to test (using Postman/Insomnia):
# Method: DELETE
# URL: http://127.0.0.1:8000/books/2
# (No body usually required)
# You'll get: {"message":"Book 2 deleted successfully!"}
# Now, if you try to GET http://127.0.0.1:8000/books/2, you'll get the "Book not found" error.

Why Does Choosing the Right Method Matter?

It might seem like you could just use POST for everything, but that's not good practice!

• Clarity: Using the correct method makes your API clear and predictable for other developers (or your future self!).
• Caching: Browsers and other systems can safely cache (store for quick access) GET requests, making web Browse faster. They won't cache POST requests because they might change data.
• Idempotency: Understanding idempotency helps prevent unintended side effects if a request is accidentally sent multiple times.
• Framework Features: FastAPI (and other web frameworks) leverage these methods to automatically handle things like routing, data validation, and documentation.

And there you have it! These four HTTP methods form the backbone of almost all web interactions you'll encounter. By understanding their purpose and how to use them, you're well on your way to building robust and professional web APIs.

Keep experimenting with your FastAPI server and Postman/Insomnia – the best way to learn is by doing! Happy coding!