Not just theory — send real HTTP requests to The Movie Database API from this page, watch the exact request and response payloads, and learn to read API docs like an engineer.
An API (Application Programming Interface) is a contract: a defined set of requests a program can make, and the responses it can expect back. Think of a restaurant — you (the client) don't walk into the kitchen (the server). You tell the waiter (the API) what you want from the menu (the documentation), and the kitchen sends back your order in a predictable format.
The docs define exactly which URLs exist, what parameters they accept, and what shape the response takes. Nothing more, nothing less.
TMDB has a massive database and recommendation engine behind it. You never see that — you just ask /movie/27205 and get JSON back.
Almost every web API works the same basic loop: you send a request, the server processes it, and sends back a response — every single time.
Most modern APIs — including TMDB's — speak HTTP, the same protocol your browser uses to load web pages. Same verbs, same status codes.
A "payload" is the actual data being sent or returned — usually as JSON. No magic, just structured text.
APIs identify who's calling, usually via an API key or token, so they can rate-limit, bill, or restrict access.
Click each colored part of this real TMDB request URL to see what it means.
The URL is the address of the exact resource or action you're asking for. Everything after the host is up to the API's documentation to define.
Every API's documentation follows roughly the same shape. Here's how developer.themoviedb.org is organized, and what each part tells you.
TMDB gives you an API Key (v3) and a Read Access Token (v4, a Bearer token). Both are secrets. If your JavaScript calls TMDB directly, anyone can open DevTools → Network tab and steal it.
Anyone viewing your page's source or network requests now has your token and can use your quota — or worse, run up costs / get you rate-limited or banned.
This is exactly what this page does. Open the Network tab during the playground below — you'll only ever see requests to /api/tmdb.php, never to TMDB directly.
Pick a real TMDB endpoint, fill in parameters, and send it. You'll see exactly what request left your server, and exactly what came back.
↑ These buttons use htmx directly: hx-get="api/tmdb.php?..." — no JavaScript written for the click, just an attribute.
fetch() instead of htmx, because we need to build the JSON tree view and reuse the same result in two columns — htmx is for swapping HTML fragments, not full client-side rendering logic.Click a card to send a real request that demonstrates that outcome.
Everything worked. The body contains the data you asked for.
The resource (e.g. that movie ID) doesn't exist. Check the URL/params.
Missing or invalid credentials — the API doesn't know who you are.
Your request is malformed — a required param is missing or invalid.
Something broke on the API's side. Not your fault — usually worth retrying.
You've hit the rate limit. Back off and check the Retry-After header.
"Payload" just means the data traveling in the request or response body. TMDB's read endpoints are all GET (no request body — params ride in the URL), so here's a real GET/response pair alongside an illustrative POST payload for comparison.
No request body. Everything needed is in the URL.
GET /3/movie/27205?append_to_response=credits Host: api.themoviedb.org Authorization: Bearer <token> Accept: application/json
TMDB's real "add rating" endpoint needs a session id we won't set up here — this shows the shape of a POST payload.
POST /3/movie/27205/rating
Host: api.themoviedb.org
Authorization: Bearer <token>
Content-Type: application/json
{
"value": 8.5
}This is real, live data returned just now by TMDB for movie id 27205 (Inception) — rendered as a collapsible tree so you can explore its shape.
Twenty questions covering everything above. No pressure — just a gut check.