The Grammar of the Web: HTTP Methods and Status Codes

If an API is a messenger, then HTTP Methods and Status Codes are the grammar and the feedback of the conversation. They ensure that both the client and the server understand exactly what is being asked and what the result of that request was.

HTTP Methods (The Verbs)

HTTP methods tell the server what action you want to perform on a specific resource. Think of these as the "verbs" of your request.

The Most Common Methods:

• GET: Used to retrieve data. It’s like asking, "Can I see the details for user 123?" (Read-only).

    // Requesting data
    GET /users/123 HTTP/1.1
    Host: example.com
   
    // Server Response
    HTTP/1.1 200 OK
    { 
        "id": 123,
        "name": "Alex",
        "email": "[email protected]"
    }

• POST: Used to create a new resource. It’s like submitting a sign-up form to create a new account.

    // Creating a new resource
    POST /users HTTP/1.1
    Host: example.com
    Content-Type: application/json
   
    { 
       "name": "John", 
        "email": "[email protected]"
    }
   
    // Server Response
    HTTP/1.1 201 Created
    { 
        "id": 124,
        "name": "John",
        "email": "[email protected]"
    }

• PUT: Used to update/replace an existing resource. It sends the entire updated version of the data.
  • The Catch: If you use PUT to update a user's name but forget to send their email, the email will be removed. It replaces the whole object.

    // Updating a resource
    PUT /users/123 HTTP/1.1
    Host: example.com
    Content-Type: application/json
   
    {
        "name": "Alexander",
        "email": "[email protected]"
    }
   
    // Server Response
    HTTP/1.1 200 OK
    { 
        "id": 123,
        "name": "Alexander",
        "email": "[email protected]"
    }

• PATCH: Used to partially update a resource. It’s like changing just your email address without resending your whole profile.
  • The Benefit: If you only send the name, only the name changes. The email stays safe. This is usually what you want for "Edit Profile" forms.

    // Partially updating a resource
    PATCH /users/124 HTTP/1.1
    Host: example.com
    Content-Type: application/json
   
    { "email": "[email protected]" }
   
    // Server Response
    HTTP/1.1 200 OK
    {
        "id": 124,
        "name": "John", 
        "email": "[email protected]"
    }

• DELETE: Used to remove a resource. It’s exactly what it sounds like—deleting a post or an account.

    // Deleting a resource
    DELETE /users/124 HTTP/1.1
    Host: example.com
   
    // Server Response
    HTTP/1.1 204 No Content

HTTP Status Codes (The Feedback)

Once the server processes your request, it sends back a three-digit status code. These codes tell the client if the request was a success, a mistake, or a total disaster.

The 5 Categories:

Status Codes You'll Use Every Day

The "Everything is Great" Codes (Success)

• 200 OK: The standard response for a successful GET or PUT.
• 201 Created: Usually returned after a successful POST request.

The "You Made a Mistake" Codes (Client Error)

• 400 Bad Request: The server didn't understand the request (maybe a typo in the JSON).
• 401 Unauthorized: You’re not logged in or don't have the right "key" to enter.
• 403 Forbidden: You’re logged in, but you don't have permission to see this specific data.
• 404 Not Found: The most famous code. The resource you're looking for doesn't exist.

The "It's Not You, It's Me" Codes (Server Error)

• 500 Internal Server Error: A generic "catch-all" error when the server's code crashes.
• 503 Service Unavailable: The server is overloaded or down for maintenance.

Testing APIs Practically: Say Hello to Postman

Right now, you might be wondering: "How do I actually send a POST request? My browser address bar only sends GET requests!"

That is entirely correct. To test APIs while you are building them, developers use specialized "API Client" tools instead of a normal web browser. These tools let you easily craft requests, attach JSON bodies, and add headers.

Highly Recommended Tools:

1. Postman: The industry standard. It has a beautiful interface for saving and organizing hundreds of different API requests.
2. Thunder Client: A fantastic, lightweight extension built directly into VS Code. You can test your APIs without ever leaving your editor.
3. Insomnia: A popular open-source alternative to Postman, favored for its clean UI.

I strongly recommend installing Thunder Client or Postman right now so you can properly test the server we are about to build!

Idempotency: A Pro Tip

In API design, we talk about Idempotency. An operation is idempotent if performing it multiple times has the same effect as performing it once.

• GET is idempotent. Looking at a page ten times doesn't change the page.
• PUT is idempotent. Replacing a file with the same version ten times leaves you with the same file.
• POST is NOT idempotent. If you click "Submit" five times on an order, you might accidentally buy five pairs of shoes!

Summary

HTTP methods and status codes are the contract between client and server—use them consistently to make APIs predictable and easy to integrate with.
Understanding these methods and codes allows you to debug your apps faster and build more reliable systems.

• Use PATCH for updates to avoid accidental data loss.
• Remember: 4xx is their fault, 5xx is your fault.

Now that we speak the language, it's time to give our application a memory. In the next post, we will connect our Node.js server to a database.

Till then, happy coding!