How the Web Works: Understanding HTTP for REST APIs

Before you can truly master REST APIs, you need to understand the foundation they are built on: HTTP (HyperText Transfer Protocol). Every single REST API call you will ever make travels over HTTP. Understanding this protocol is like understanding the roads before learning to drive.

In this module, we will break down exactly how HTTP works, what a request looks like under the hood, what a response contains, and how to read both like a professional developer.

---

1. What Is HTTP?

HTTP (HyperText Transfer Protocol) is the communication protocol of the World Wide Web. It defines how messages are formatted, transmitted, and processed between a client (like your browser or a mobile app) and a server (like a web application backend).

When you type https://google.com into your browser, you are making an HTTP request. When Google sends back the search page, that is an HTTP response. Every web interaction follows this same pattern.

The Request-Response Cycle

HTTP follows a strict request-response model:

1. The client sends a request to the server.
2. The server processes the request.
3. The server sends a response back to the client.

sequenceDiagram
    participant Client as Client - Browser/App
    participant Server as Server - API Backend

    Client->>Server: HTTP Request
    Note right of Server: Server processes the request
    Server-->>Client: HTTP Response
    Note left of Client: Client processes the response

This is a synchronous process. The client sends a request, waits, and receives a response. There is no ongoing connection (unlike WebSockets). Each request-response pair is an independent transaction.

HTTP vs HTTPS

You will often see HTTPS instead of HTTP. The "S" stands for Secure. HTTPS encrypts the data being transmitted using TLS (Transport Layer Security), preventing third parties from reading or modifying the data in transit.

For REST APIs, always use HTTPS in production. The mechanics of the protocol (methods, headers, status codes) are identical between HTTP and HTTPS.

---

2. Anatomy of an HTTP Request

An HTTP request is the message you send to a server asking it to do something. Every request has four components:

graph TD
    A[HTTP Request] --> B[Method]
    A --> C[URL]
    A --> D[Headers]
    A --> E[Body]

    B --> B1["GET, POST, PUT, DELETE"]
    C --> C1["https://api.example.com/users/42"]
    D --> D1["Content-Type: application/json<br/>Authorization: Bearer token123"]
    E --> E1["JSON payload with data"]

    style A fill:#4f46e5,color:#fff
    style B fill:#0891b2,color:#fff
    style C fill:#0891b2,color:#fff
    style D fill:#0891b2,color:#fff
    style E fill:#0891b2,color:#fff

Component 1: The HTTP Method

The method (also called a verb) tells the server what action you want to perform. The most common methods are:

Method	Purpose	Has Body?	Example
GET	Retrieve data	No	Get a user's profile
POST	Create new data	Yes	Create a new account
PUT	Replace existing data	Yes	Update an entire user profile
PATCH	Partially update data	Yes	Change just the email address
DELETE	Remove data	Usually No	Delete a user account

Think of it like this:

• GET = "Show me"
• POST = "Create this"
• PUT = "Replace this entirely"
• PATCH = "Update part of this"
• DELETE = "Remove this"

Component 2: The URL (Endpoint)

The URL (Uniform Resource Locator) tells the server which resource you want to act on. In REST APIs, URLs are called endpoints.

A URL has several parts:

https://api.example.com:443/v2/users/42?include=orders&limit=10
|_____|_________________|___|_____________|________________________|
  |          |            |       |                    |
Protocol    Host         Port  Path           Query Parameters

Part	Description	Example
Protocol	HTTP or HTTPS	https://
Host	The server address	api.example.com
Port	Network port (usually implicit)	:443 (default for HTTPS)
Path	The specific resource	/v2/users/42
Query Parameters	Filters or options	?include=orders&limit=10

Component 3: Headers

Headers are key-value pairs that provide metadata about the request. They tell the server important information about what you are sending and what you expect back.

Common request headers:

Header	Purpose	Example Value
Content-Type	Format of the body data	application/json
Accept	Format you want back	application/json
Authorization	Authentication credentials	Bearer eyJhbGciOi...
User-Agent	Client identification	Mozilla/5.0...
Cache-Control	Caching instructions	no-cache

Component 4: Body (Payload)

The body contains the actual data you are sending to the server. Not all requests have a body:

• GET and DELETE requests typically do not have a body.
• POST, PUT, and PATCH requests typically do have a body.

The body is usually formatted as JSON:

{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "role": "developer"
}

A Complete HTTP Request

Here is what a complete HTTP request looks like when you break it down:

POST /api/v1/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer abc123token
Accept: application/json

{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "role": "developer"
}

And here is the same request using cURL:

curl -X POST https://api.example.com/api/v1/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer abc123token" \
  -d '{
    "name": "Jane Doe",
    "email": "jane@example.com",
    "role": "developer"
  }'

---

3. Anatomy of an HTTP Response

After the server processes your request, it sends back a response. The response tells you whether the operation succeeded and provides any requested data.

A response has three components:

graph TD
    A[HTTP Response] --> B[Status Code]
    A --> C[Headers]
    A --> D[Body]

    B --> B1["200 OK, 201 Created, 404 Not Found"]
    C --> C1["Content-Type: application/json<br/>X-Request-ID: abc-123"]
    D --> D1["JSON data with the result"]

    style A fill:#4f46e5,color:#fff
    style B fill:#059669,color:#fff
    style C fill:#059669,color:#fff
    style D fill:#059669,color:#fff

Status Code

The status code is a three-digit number that immediately tells you the result of your request. They are grouped by the first digit:

Range	Category	Meaning
1xx	Informational	Request received, continuing
2xx	Success	Your request worked
3xx	Redirection	Resource moved somewhere else
4xx	Client Error	You made a mistake
5xx	Server Error	The server had a problem

The most important status codes for REST APIs:

Code	Name	When You See It
200	OK	GET request succeeded
201	Created	POST request created a resource
204	No Content	DELETE succeeded, nothing to return
400	Bad Request	Your request data was invalid
401	Unauthorized	You are not authenticated
403	Forbidden	You are authenticated but not allowed
404	Not Found	The resource does not exist
422	Unprocessable Entity	Data format is correct but values are wrong
429	Too Many Requests	You hit a rate limit
500	Internal Server Error	Something broke on the server
503	Service Unavailable	Server is temporarily down

Response Headers

Response headers provide metadata about the response:

Header	Purpose	Example
Content-Type	Format of response body	application/json
Content-Length	Size of response in bytes	256
X-Request-ID	Unique ID for debugging	req-abc-123-def
X-RateLimit-Remaining	API calls remaining	98
Cache-Control	How long to cache	max-age=3600

Response Body

The response body contains the actual data. For REST APIs, this is almost always JSON:

{
  "id": 42,
  "name": "Jane Doe",
  "email": "jane@example.com",
  "role": "developer",
  "created_at": "2026-02-22T10:30:00Z"
}

A Complete HTTP Response

Here is what a complete HTTP response looks like:

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/users/42
X-Request-ID: req-abc-123

{
  "id": 42,
  "name": "Jane Doe",
  "email": "jane@example.com",
  "created_at": "2026-02-22T10:30:00Z"
}

---

4. The Complete HTTP Flow

Let us trace a complete HTTP interaction from start to finish:

graph TD
    A[Client prepares request] --> B[Set Method: GET]
    B --> C["Set URL: /posts/1"]
    C --> D[Add Headers]
    D --> E[Send over HTTPS]
    E --> F[Server receives request]
    F --> G[Server processes request]
    G --> H[Server queries database]
    H --> I[Server builds response]
    I --> J[Set Status Code: 200]
    J --> K[Set Response Headers]
    K --> L[Add JSON Body]
    L --> M[Send response to client]
    M --> N[Client receives response]
    N --> O[Client parses JSON]
    O --> P[Client displays data]

    style A fill:#4f46e5,color:#fff
    style F fill:#059669,color:#fff
    style N fill:#0891b2,color:#fff

Live Example

Let us trace this with a real API call:

curl -v https://jsonplaceholder.typicode.com/posts/1

The -v flag (verbose) shows you the full HTTP conversation. You will see output like:

> GET /posts/1 HTTP/2
> Host: jsonplaceholder.typicode.com
> User-Agent: curl/8.4.0
> Accept: */*
>
< HTTP/2 200
< content-type: application/json; charset=utf-8
< cache-control: max-age=43200
<
{
  "userId": 1,
  "id": 1,
  "title": "sunt aut facere repellat provident...",
  "body": "quia et suscipit..."
}

Lines starting with > are what you sent (the request). Lines starting with < are what you received (the response).

---

5. HTTP Methods in Detail

Let us look at each HTTP method with real, working examples using the JSONPlaceholder API.

GET - Retrieve Data

GET is the simplest and most common method. It retrieves data without changing anything on the server.

# Get all posts
curl https://jsonplaceholder.typicode.com/posts

# Get a specific post
curl https://jsonplaceholder.typicode.com/posts/1

# Get comments for a specific post
curl https://jsonplaceholder.typicode.com/posts/1/comments

Key rules for GET:

• Should never modify data on the server
• Should be idempotent (calling it 100 times gives the same result)
• Does not have a request body

POST - Create Data

POST creates a new resource on the server.

curl -X POST https://jsonplaceholder.typicode.com/posts \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My First Post",
    "body": "This is the content of my post.",
    "userId": 1
  }'

Response (201 Created):

{
  "title": "My First Post",
  "body": "This is the content of my post.",
  "userId": 1,
  "id": 101
}

Notice the server assigned an id of 101 to the newly created resource.

PUT - Replace Data

PUT replaces an entire resource with the data you provide.

curl -X PUT https://jsonplaceholder.typicode.com/posts/1 \
  -H "Content-Type: application/json" \
  -d '{
    "id": 1,
    "title": "Updated Title",
    "body": "Completely new body content.",
    "userId": 1
  }'

Key difference from PATCH: PUT replaces the entire resource. If you leave out a field, it gets removed.

DELETE - Remove Data

DELETE removes a resource from the server.

curl -X DELETE https://jsonplaceholder.typicode.com/posts/1

This returns a 200 OK or 204 No Content status code with an empty body.

---

6. Understanding HTTP Headers in Practice

Headers are one of the most overlooked aspects of HTTP, but they are critical for professional API work.

Content Negotiation

Headers allow the client and server to agree on data formats:

# Tell the server you want JSON back
curl -H "Accept: application/json" \
  https://jsonplaceholder.typicode.com/posts/1

# Tell the server you are sending JSON
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"title": "Test"}' \
  https://jsonplaceholder.typicode.com/posts

Authentication Headers

Most real-world APIs require authentication via headers:

# API Key authentication
curl -H "X-API-Key: your-api-key-here" \
  https://api.example.com/data

# Bearer Token authentication (JWT)
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  https://api.example.com/protected/data

Custom Headers

APIs often use custom headers prefixed with X-:

# Rate limit headers in response
# X-RateLimit-Limit: 100
# X-RateLimit-Remaining: 97
# X-RateLimit-Reset: 1708640000

---

7. HTTP Versions

You might see references to different HTTP versions. Here is a quick overview:

Version	Year	Key Feature
HTTP/1.0	1996	One request per connection
HTTP/1.1	1997	Persistent connections, chunking
HTTP/2	2015	Multiplexing, header compression
HTTP/3	2022	QUIC protocol, faster connections

For REST API work, the version rarely matters to you as a client. The methods, headers, and status codes work the same across all versions. The differences are in performance and connection management, which are handled by the infrastructure.

---

8. The Request-Response Pipeline

Here is a comprehensive view of what happens during an API call:

graph LR
    subgraph Client Side
        A[Build Request] --> B[DNS Lookup]
        B --> C[TCP Handshake]
        C --> D[TLS Handshake]
        D --> E[Send HTTP Request]
    end

    subgraph Server Side
        F[Receive Request] --> G[Route to Handler]
        G --> H[Validate Input]
        H --> I[Business Logic]
        I --> J[Query Database]
        J --> K[Build Response]
    end

    subgraph Response
        L[Send HTTP Response] --> M[Client Receives]
        M --> N[Parse Response]
        N --> O[Handle Result]
    end

    E --> F
    K --> L

    style A fill:#4f46e5,color:#fff
    style F fill:#059669,color:#fff
    style L fill:#0891b2,color:#fff

Understanding this pipeline helps you debug issues:

• DNS errors: Wrong hostname
• Connection errors: Server is down or blocked
• 4xx errors: Your request has a problem
• 5xx errors: The server has a problem
• Timeout: The server took too long to respond

---

Summary and Key Takeaways

1. HTTP is the protocol that REST APIs use to communicate. Understanding it is essential.
2. Requests have four parts: Method, URL, Headers, and Body.
3. Responses have three parts: Status Code, Headers, and Body.
4. HTTP methods map to CRUD operations: GET (Read), POST (Create), PUT (Update), DELETE (Delete).
5. Status codes instantly tell you if a request succeeded (2xx), had a client error (4xx), or a server error (5xx).
6. Headers carry metadata about the request and response, including content type and authentication.
7. Use curl -v to see the full HTTP conversation for debugging.

---

Lesson Review Quiz

---

Practice Exercise

1. Run each of these commands in your terminal and observe the differences:

# See the full HTTP conversation with verbose output
curl -v https://jsonplaceholder.typicode.com/posts/1

# See only the response headers
curl -I https://jsonplaceholder.typicode.com/posts/1

# See the response with headers included
curl -i https://jsonplaceholder.typicode.com/posts/1

2. Compare the output of -v, -I, and -i flags. Each gives you different levels of HTTP detail.

3. Try making a request to a URL that does not exist and observe the status code:

curl -v https://jsonplaceholder.typicode.com/posts/99999

In the next module, we will dive into REST Fundamentals and learn how to design clean, professional API endpoints.