REST API Basics: The Language of the Web

FastAPI is a tool for building REST APIs. Before we can build them effectively, we must understand the protocol that powers almost everything we do online: HTTP (HyperText Transfer Protocol).

In this lesson, we explore the grammar of the web: Methods, Status Codes, and the Request-Response Lifecycle.

---

1. The Request-Response Lifecycle

Every time you type a URL into a browser or an app calls an API, a predictable cycle occurs:

1. The Client (e.g., your browser or a mobile app) sends an HTTP Request.
2. The Server (our FastAPI app) receives the request and processes it.
3. The Server sends back an HTTP Response.
4. The Client renders the data or shows an error.

---

2. HTTP Methods (Verbs)

If the URL is the "Noun" (e.g., /users/123), the HTTP Method is the Verb. It tells the server what action to take.

Method	Purpose	Use Case
GET	Retrieve data	Fetching a profile, list of products
POST	Create data	Registering a user, submitting a post
PUT	Replace/Update data	Changing the entire user profile
PATCH	Partial update	Changing just the user's email
DELETE	Remove data	Deleting a file or a comment

In FastAPI, these map directly to decorators:

@app.get("/items")
@app.post("/items")

---

3. HTTP Status Codes

When the server responds, it includes a three-digit status code. This is the server's way of saying "I heard you, and here is what happened."

The "Family" of Status Codes:

• 2xx (Success):
  • 200 OK: Mission accomplished.
  • 201 Created: Usually sent after a successful POST.
• 4xx (Client Error):
  • 400 Bad Request: The client sent something nonsensical.
  • 401 Unauthorized: Who are you? (Missing auth).
  • 403 Forbidden: I know who you are, but you can't touch this.
  • 404 Not Found: It’s not here.
• 5xx (Server Error):
  • 500 Internal Server Error: The developer (maybe you!) made a mistake in the code.

---

4. HTTP Headers

Headers are "metadata" attached to the request or response. They provide extra information without being part of the main payload.

Common Headers:

• Content-Type: Tells the client/server what format the data is in (usually application/json in FastAPI).
• Authorization: Carries the credentials (like a JWT token) to prove the user's identity.
• User-Agent: Tells the server what device or browser is making the request.

---

Visualizing the Request

sequenceDiagram
    participant C as Client (React App)
    participant S as Server (FastAPI)
    participant D as Database
    
    C->>S: POST /login (Credentials in Body)
    S->>D: Verify User
    D-->>S: User Found
    S-->>C: 200 OK (JWT Token in Headers)

---

Summary

• REST follows a stateless Request-Response pattern.
• Methods define the action (GET to read, POST to create).
• Status Codes define the outcome (200 for win, 404 for loss).
• Headers provide the context (Auth, Content-Type).

In the next lesson, we wrap up Module 2 with JSON and API Design Principles, ensuring our data structures are as robust as our logic.

---

Exercise: The Right Status

If a user tries to delete a post that doesn't exist, what status code should you return? Hint: Is it a success, a client error, or a server error?