How REST APIs work, explained for beginners

You have probably heard "just call the API" a hundred times. Weather apps, payment buttons, login with Google, the feed on your phone: nearly all of it runs on REST APIs. But most explanations either stay vague ("it lets programs talk to each other") or jump straight into server code.

This guide takes a different route. We will follow a single request from your code to a server and back, and look at every piece along the way. There is nothing to build or install, and the example calls a real, free API, so you can run it yourself. By the end you will be able to read an API's documentation, understand what each part of a request and response means, and know what people mean when they call an API "RESTful".

The short answer

An API is a menu a program offers to other programs. It lists what you can ask for and how to ask. REST is a set of conventions for designing that menu on top of HTTP, the same protocol your browser uses to load web pages.

The conventions matter more than the acronym. Because most web APIs follow the same handful of rules, learning to read one teaches you to read nearly all of them.

Follow one request

Our example is the Studio Ghibli API, a free, open-source API with data about the studio's films. It needs no account and no key. You want the first two films, so your program, called the client, sends this message:

GET /films?limit=2&fields=id,title,release_date HTTP/1.1
Host: ghibliapi.vercel.app
Accept: application/json

Every HTTP request has the same parts:

The request line. The method (GET), the path (/films), and an optional query string (?limit=2&fields=id,title,release_date) that narrows down what you want. Here it asks for two films and only three fields.
Headers. Extra information, one per line. Host says which server you are talking to, and Accept says what format you would like back.
A body. Not here, because GET only reads. Requests that send data, like creating a record, put it in the body.

The server, which is the program waiting for requests, replies:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
 
[
  {
    "id": "2baf70d1-42bb-4437-b551-e5fed5a87abe",
    "title": "Castle in the Sky",
    "release_date": "1986"
  },
  {
    "id": "12cfb892-aac0-4c5b-94af-521852e46d6a",
    "title": "Grave of the Fireflies",
    "release_date": "1988"
  }
]

(The real response carries more headers than this. We kept the ones that matter here.)

A response has three parts too: a status line that says how it went (200 OK), headers that describe the reply (Content-Type says the body is JSON), and the body with the data you asked for.

That is the whole conversation. Every API call you will ever make is a variation on it. The lessons Clients And Servers (opens in a new tab), Reading Headers (opens in a new tab) and Read The Whole Response (opens in a new tab) let you inspect real requests and responses like these.

URLs name things, methods say what to do

The first REST idea is that a URL names a resource: a thing, such as a film, a user or an order. The method says what to do with it.

Good API paths are nouns, usually plural, and they nest when one thing belongs to another. This API has paths like these:

/films                                         the collection of all films
/films/2baf70d1-42bb-4437-b551-e5fed5a87abe    one film
/people                                        the collection of all characters

Many APIs nest further, such as /users/7/orders for the orders that belong to user 7. Compare all of that with the style REST moves away from, where the verb lives in the URL:

/getFilm?id=2baf70d1-42bb-4437-b551-e5fed5a87abe
/deleteFilm?id=2baf70d1-42bb-4437-b551-e5fed5a87abe

When the method carries the verb, you need far fewer URLs and every API feels familiar. Thinking In Resources (opens in a new tab) shows how to turn a real idea into a set of resources, and Query Strings (opens in a new tab) covers options like ?limit=2.

There is one more thing about methods that tutorials often skip: how they behave when a request is repeated. Networks fail, and clients retry, so it matters.

Method	Typical use	Changes data?	Safe to repeat?
`GET`	Read	No	Yes
`POST`	Create	Yes	No: two sends can create two records
`PUT`	Replace	Yes	Yes: same result every time
`PATCH`	Change part of something	Yes	Not guaranteed
`DELETE`	Remove	Yes	Yes: it is gone either way

This is why a browser asks "resubmit the form?" after a refresh on a page that used POST, but never for a plain page load.

Status codes tell you who needs to act

The first digit of a status code groups it into a family, and the family tells you where the problem is:

2xx: it worked. 200 OK, 201 Created, 204 No Content.
3xx: look somewhere else. The thing moved, and the response says where.
4xx: your request has a problem. You are the one who has to change something. 401 means the server does not know who you are, 403 means it knows but will not allow it, 404 means nothing lives at that URL, and 429 means you are sending too many requests.
5xx: the server has a problem. Your request may be fine, and retrying later might work.

When something breaks, read the first digit before anything else. A 4xx sends you to your own code, and a 5xx usually means waiting or telling whoever runs the API. Ask the Ghibli API for /films/not-a-real-id and you get a 404: the request was well formed, but nothing lives there. Status Codes (opens in a new tab) walks through the codes you will see most.

Every request stands alone

The second big REST idea is that the server remembers nothing between requests. This is called being stateless. Each request has to carry everything the server needs to answer it, including who you are, if it needs to know.

The Ghibli API is public, so it never asks. Most APIs that hold private data or limit usage do ask, and they expect a key in a header on every call:

Authorization: Bearer your-api-key

It is not sent once at the start of a "session"; it travels with every request. The server checks it, answers, and forgets you until the next one.

It sounds inconvenient, but it makes APIs simple to scale. Any server in a group can answer any request, because none of them is holding a conversation with you.

JSON is the language of the body

The Content-Type header says how to read the body. Most REST APIs use JSON, a text format that looks like JavaScript objects and arrays, which is why JavaScript developers pick it up so quickly.

Here is the same request from the top, sent from JavaScript with fetch. It is a real call, so you can run it as it is:

const response = await fetch(
  "https://ghibliapi.vercel.app/films?limit=2&fields=id,title,release_date"
)
 
if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`)
}
 
const films = await response.json()
console.log(films[0].title) // "Castle in the Sky"

Two details are worth noticing. fetch does not throw on a 404 or 500; it only fails if the network itself fails, so you check response.ok yourself. And response.json() is asynchronous, which is why this code uses await. If that part is new, JavaScript async/await explained, without the confusion covers it.

What "RESTful" really means

People call an API RESTful when it follows most of these habits:

Resources have URLs. Nouns, not verbs.
Standard methods do the work. GET reads, POST creates, and so on.
Requests are stateless. Everything needed travels with the request.
Status codes are honest. A failure is not a 200 with an error message hidden in the body.
Responses are consistent. The same shape of JSON, the same style of errors.

REST is a style, not a standard, and there is no certification. Real APIs bend the rules, and that is fine. What matters is that you can predict how an API behaves before you read its docs.

Common beginner mix-ups

"REST is a library." It is a design style. You can follow it in any language.
"An API is a website without the design." Close. Both use HTTP, but a website returns HTML for people and an API returns data for programs.
"A 200 means my request did what I wanted." It means the server processed it. Some APIs, against the conventions, return 200 even for errors, so read the body too.
"I should send everything with POST." It works, but you lose the safe-to-repeat behaviour and everyone's expectations of how the API acts.

Ready to build one?

You now know what happens on both sides of the conversation. Writing the server side is the natural next step, and Build a REST API with Node.js and Express takes the ideas above and turns them into a working bookshelf API in about 50 lines. Everything runs in your browser on start.dev, so there is nothing to set up.

Want to check your understanding first? How The Web Talks Knowledge Check (opens in a new tab) covers requests, methods and status codes in a short quiz.

Keep going

APIs are one of the most useful ideas in programming, because almost everything you build will either offer one or call one. The full course, Building APIs with Node.js & Express (opens in a new tab), walks you from these concepts to a structured API with middleware, routers and saved data.

If the JavaScript in this post felt shaky, especially async and await, the courses below will give you the footing for it.

Check out our related courses

Intermediate

Intermediate JavaScript

Level up from the basics to modern, idiomatic JavaScript. Transform data with array methods, master destructuring and spread, handle async code with promises and async/await, and load live API data. Assumes you have finished JavaScript Basics and JavaScript DOM.

Instructor

JavaScript Basics

Learn the JavaScript language fundamentals (variables, types, control flow, arrays, objects, and functions) by running small programs in the console.

Instructor

Building APIs with Node.js & Express

Go from consuming APIs to building them. Learn how HTTP works from the wire up, then build JSON APIs with Node.js and Express: routes, middleware, controllers, and a full CRUD project.

Instructor