An API (Application Programming Interface) is a contract between software systems that defines how they communicate. It specifies what requests you can make, what data to send, and what responses you'll get back.

What is the HTTP request-response cycle?

A client sends an HTTP request (with a method like GET or POST, a URL path, and optional body/headers) to a server. The server processes it and returns an HTTP response with a status code and data, typically in JSON format.

What is an API?

Fundamentals

Your frontend is talking to your backend. But how? And what happens when the conversation breaks down?

You build a frontend, deploy it, and try to fetch data from your backend. The browser console shows a CORS error. Your frontend can see the backend, but the browser blocks every request.

terminal

Access to fetch at 'http://localhost:8000/api' from origin 'http://localhost:3000' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present.

Question

Why would the browser block a request that clearly works when you test it with curl or Postman? The answer is baked into how the web works — and understanding it starts with understanding what an API actually is.

The Big Picture: How APIs Work

Every API interaction follows the same pattern. Your client sends a request, the server processes it, and sends back a response. That's it. Everything else is details.

Client

Your browser or app

HTTP Request

GET, POST, etc.

Server

Your FastAPI app

HTTP Response

Data + status code

Client

Renders the data

So What Does "API" Actually Mean?

API stands for Application Programming Interface. Think of it as a contract: "Send me data in this shape, and I'll send you data back in that shape."

You never touch the server's database directly. You never see its internal code. You just talk to the API, and it handles everything behind the scenes.

Real-world

It's like ordering at a restaurant. You tell the waiter what you want (the API), and the kitchen (the server) makes it. You never walk into the kitchen yourself — the waiter handles the back-and-forth.

APIs 101

What you just learned

An API is a contract between software systems — it defines how they talk to each other

Clients send requests, servers send responses — that's the whole cycle

You never access the server's internals directly — the API is the go-between

HTTP: The Language Your API Speaks

HTTP is how clients and servers communicate. Every time you hit an API, you're sending an HTTP request. Every response you get back? Also HTTP. A request has a method (GET, POST, etc.), a URL, headers, and optionally a body. A response has a status code, headers, and the data.

http-example.txt

# Here's a full HTTP conversation
# Your client sends this:
GET /api/items/42 HTTP/1.1
Host: example.com
Accept: application/json

# The server responds with this:
HTTP/1.1 200 OK
Content-Type: application/json

{"id": 42, "name": "Widget", "price": 9.99}

JSON: How Your Data Travels

JSON (JavaScript Object Notation) is the standard data format for APIs. If you know Python dictionaries, you basically already know JSON. There are just a couple of quirks.

json_example.py

# Python dictionary — looks familiar, right?
item = {
    "name": "Widget",
    "price": 9.99,
    "tags": ["electronics", "sale"],
    "in_stock": True,    # Python uses True (capital T)
}

# Same data as JSON (spot the difference!)
# {"name": "Widget", "price": 9.99, "tags": ["electronics", "sale"], "in_stock": true}
# JSON uses true (lowercase t) — that's basically the only gotcha

HTTP & JSON

What you just learned

HTTP is the protocol — it carries requests and responses between client and server

Methods (GET, POST, etc.) tell the server what you want to do

JSON is how data travels — it's almost identical to Python dicts

Status Codes: What the Server Is Telling You

Ever seen a 404? That's a status code. Every HTTP response includes one, and it tells you what happened. Here are the ones you'll run into constantly when building APIs.

Insight

Think of status codes as the server's one-word answer before the details. 200 = "Sure, here you go." 404 = "Never heard of it." 500 = "Something broke and it's not your fault."

200

Request succeeded

201

Created

Resource was created

204

No Content

Success, no body returned

400

Bad Request

Malformed request syntax

401

Unauthorized

Missing or invalid auth

404

Not Found

Resource does not exist

422

Validation Error

Data failed validation

500

Internal Server Error

Something broke on the server

Status codes

What you just learned

2xx means success — the server did what you asked

4xx means you messed up — bad request, missing auth, wrong URL

5xx means the server messed up — something crashed on their end

422 is FastAPI's favorite — it means your data didn't pass validation

Try It: Build a Request

Pick a scenario, hit Send, and watch the full HTTP conversation play out — from request to response.

Think about it...

If you send a POST request with no body to an endpoint that expects JSON, what status code do you get back?

Hint: Think about what FastAPI does with Pydantic models...

Key Points

APIs Are Contracts

They define how software systems communicate without exposing internals

HTTP Is the Protocol

Requests and responses flow over HTTP with methods, URLs, headers, and bodies

JSON Is the Format

Structured data travels as JSON — nearly identical to Python dicts

Status Codes Communicate Results

2xx for success, 4xx for client errors, 5xx for server errors