🚦 HTTP Methods, Headers, and Status Codes

The Three Building Blocks

Every HTTP exchange is a short, structured message. Strip away the details and each request answers three questions, and each response answers one more:

• What action? → the method (GET, POST, DELETE…)
• On which thing? → the URL (the resource)
• With what extra details? → the headers (and sometimes a body)
• And how did it go? → the response's status code

💡 The language analogy. HTTP is a tiny language. Methods are its verbs ("GET" = "please give me"). URLs are its nouns (/users/123 = "the user with ID 123"). Headers are the adjectives and adverbs ("Accept: application/json" = "reply in JSON, please"). And status codes are the short replies ("200" = "done", "404" = "couldn't find it"). Fluency means knowing both the words and how they fit together.

HTTP Methods (Verbs)

A method declares the operation you want to perform on a resource. Five carry almost all of the weight in day-to-day API work:

Here is the full lifecycle of a single resource, expressed as methods against a REST-style URL:

PUT vs PATCH — the most common mix-up

PUT replaces the whole resource. Send the complete representation; any field you omit is treated as removed or reset. PATCH updates only the fields you send. If you only want to change a price, PATCH is the right tool:

PATCH /api/products/42
Content-Type: application/json

{ "price": 139.99 }

Safety & Idempotency

Two properties decide how a method may be used, cached, and retried. They sound academic but they cause real bugs when ignored.

HTTP Headers

Headers are key–value metadata attached to requests and responses. They never carry the "main" payload — that's the body — but they tell each side how to interpret and handle it.

Headers you will use constantly

Security headers — set these on every response

A handful of response headers harden your app against common browser-side attacks. They cost nothing and stop a whole class of bugs:

• Content-Security-Policy: default-src 'self' — controls which sources may load scripts, styles, and images; your strongest defense against XSS.
• Strict-Transport-Security: max-age=31536000; includeSubDomains — forces HTTPS for future visits.
• X-Content-Type-Options: nosniff — stops the browser from guessing (and mis-guessing) content types.
• X-Frame-Options: DENY — prevents your pages being embedded in a hostile <iframe> (clickjacking).

Status Codes

The response status code is a three-digit number grouped into five classes. The first digit tells you the category at a glance:

The single most useful skill here is telling 4xx from 5xx: a 4xx means the client must fix the request; a 5xx means the server must fix itself. Below are the codes you will reach for daily.

Worked Example: The Same Endpoint in Three Languages

Let's build a "create a product" endpoint that puts all three building blocks to work: it accepts a POST, reads and sets headers, validates the body, and returns the right status code for each outcome. Notice how the idea is identical across stacks.

Node.js (Express)

import express from 'express';
const app = express();
app.use(express.json()); // parse JSON request bodies

app.post('/api/products', (req, res) => {
  const { name, price } = req.body;

  // 400: the request itself is malformed
  if (!name || price == null) {
    return res.status(400).json({
      code: 'INVALID_INPUT',
      message: 'Both "name" and "price" are required.'
    });
  }

  // 403: authenticated, but not allowed
  if (!req.user?.isAdmin) {
    return res.status(403).json({
      code: 'FORBIDDEN',
      message: 'Only administrators can create products.'
    });
  }

  // 409: conflicts with existing state
  if (db.findByName(name)) {
    return res.status(409).json({
      code: 'PRODUCT_EXISTS',
      message: 'A product with that name already exists.'
    });
  }

  const product = db.create({ name, price });

  // 201 + Location header + security header
  res.set('X-Content-Type-Options', 'nosniff')
     .location(`/api/products/${product.id}`)
     .status(201)
     .json(product);
});

app.listen(3000);

Python (Flask)

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.post('/api/products')
def create_product():
    data = request.get_json(silent=True) or {}
    name, price = data.get('name'), data.get('price')

    if not name or price is None:
        return jsonify(code='INVALID_INPUT',
                       message='Both "name" and "price" are required.'), 400

    if not current_user_is_admin():
        return jsonify(code='FORBIDDEN',
                       message='Only administrators can create products.'), 403

    if db.find_by_name(name):
        return jsonify(code='PRODUCT_EXISTS',
                       message='A product with that name already exists.'), 409

    product = db.create(name=name, price=price)

    resp = jsonify(product)
    resp.status_code = 201
    resp.headers['Location'] = f"/api/products/{product['id']}"
    resp.headers['X-Content-Type-Options'] = 'nosniff'
    return resp

PHP

<?php
header('Content-Type: application/json');
header('X-Content-Type-Options: nosniff');

$data  = json_decode(file_get_contents('php://input'), true) ?? [];
$name  = $data['name']  ?? null;
$price = $data['price'] ?? null;

if (!$name || $price === null) {
    http_response_code(400);
    echo json_encode(['code' => 'INVALID_INPUT',
        'message' => 'Both "name" and "price" are required.']);
    exit;
}

if (!currentUserIsAdmin()) {
    http_response_code(403);
    echo json_encode(['code' => 'FORBIDDEN',
        'message' => 'Only administrators can create products.']);
    exit;
}

if ($db->findByName($name)) {
    http_response_code(409);
    echo json_encode(['code' => 'PRODUCT_EXISTS',
        'message' => 'A product with that name already exists.']);
    exit;
}

$product = $db->create($name, $price);
http_response_code(201);
header("Location: /api/products/{$product['id']}");
echo json_encode($product);

HTTP/1.1 201 Created
Location: /api/products/42
Content-Type: application/json

{ "id": 42, "name": "Wireless Headphones", "price": 129.99 }

Best Practices

Hands-on Exercise

Summary & Quiz

📚 Further Reading

• MDN — HTTP request methods
• MDN — HTTP response status codes
• MDN — HTTP headers reference
• RFC 9110 — HTTP Semantics (the current spec)

🚀 What's Next?

Now that you can speak HTTP fluently, the next lesson steps up to architecture: RESTful API Design Principles shows how to organize these methods and URLs into a clean, predictable, resource-oriented API.