REST stands for Representational State Transfer. It was introduced by computer scientist Roy Fielding in his year 2000 doctoral dissertation, and it has since become the most popular style for designing Web APIs. Almost every modern app I use — social media, banking, food delivery, streaming — is talking to a REST API in the background.
What Is a REST API?
A REST API is a Web API that follows the principles of REST. In practice, this usually means:
- Data is organized around resources (think: “users,” “orders,” “products,” “posts”) rather than around actions.
- Each resource has its own unique URL, called an endpoint (for example,
/users/42represents user number 42). - Standard HTTP methods are used to describe what I want to do with that resource:
GET— retrieve data (read a user’s profile)POST— create new data (create a new user)PUTorPATCH— update existing data (edit a user’s profile)DELETE— remove data (delete a user’s account)
- Responses are usually returned in JSON format, though XML is also technically possible.
- The API is stateless — meaning the server doesn’t remember anything about the client between requests; each request must contain all the information the server needs to process it.
A Simple REST API Example
Imagine a book store’s REST API. It might look like this:
| HTTP Method | Endpoint | What it does |
|---|---|---|
GET | /books | Get a list of all books |
GET | /books/101 | Get details of the book with ID 101 |
POST | /books | Add a new book |
PUT | /books/101 | Update all details of book 101 |
PATCH | /books/101 | Update part of book 101 (like just the price) |
DELETE | /books/101 | Delete book 101 |
This clean, predictable pattern is exactly why REST became so popular — once I understand the pattern, I can guess how most REST APIs work, even ones I’ve never used before. That predictability is a huge part of REST’s appeal.
What a Typical Response Looks Like
If I send a GET request to /books/101, a REST API would typically respond with something like this, along with a 200 OK status code:
{
"id": 101,
"title": "Clean Code",
"author": "Robert C. Martin",
"inStock": true,
"price": 24.99
}
If I tried to fetch a book that doesn’t exist, like /books/9999, a well-built REST API would respond with a 404 Not Found status code instead, along with a clear error message — not just silently return nothing.
REST API vs “RESTful” API
I often see the term “RESTful API” used interchangeably with “REST API.” Technically, “RESTful” just means an API that follows REST principles reasonably well. Very few real-world APIs implement every single constraint of REST perfectly, so “RESTful” is often used as a more relaxed, practical label for APIs that follow most of REST’s ideas without being dogmatic about every rule.
Why REST Became So Dominant
Before REST became mainstream, many Web APIs used a heavier, more complex style called SOAP (Simple Object Access Protocol), which relied on strict XML messaging formats and complicated tooling. REST’s simplicity — using plain HTTP methods and easy-to-read JSON — made it dramatically easier for developers to build and consume APIs quickly, which is a big reason it took over as the industry standard.
Common Mistakes I See in “REST” APIs
A few things I regularly notice in APIs that call themselves REST but aren’t quite following the style properly:
- Using verbs in URLs, like
/getBook?id=101instead ofGET /books/101. True REST design keeps actions in the HTTP method, not the URL. - Ignoring status codes, and returning
200 OKfor everything — even errors — with the actual error buried inside the JSON body. - Storing session state on the server, which breaks REST’s statelessness constraint and can cause scaling problems later.
None of these mistakes make an API unusable, but they do make it less predictable and harder for other developers to work with — which defeats a lot of the point of following REST in the first place.
Final Thoughts
A REST API is really just a predictable, resource-based way of exposing data and functionality over the web, using standard HTTP methods and (usually) JSON. Once the pattern clicks, reading unfamiliar REST APIs becomes far less intimidating, because most of them follow the exact same shape.