REST APIs Explained

Open any app on your phone, like a weather app, and look what happens:

• You open it, and a second later it shows today’s temperature, the forecast, all of it.
• But that data isn’t stored inside the app. It lives on a server somewhere far away.
• So how does the app reach out, ask that server for the weather, and get an answer back? That’s the question.

The app and the server have never met. They might be written in totally different languages. And yet they manage to talk just fine. The thing that lets them do that is usually a REST API. By the end of this lesson, you’ll know exactly what that means and how it works.

🎯 The Problem

Here’s the pain. Imagine you’re building that weather app, and you need data from a server:

• The app runs on a phone. The server runs in some data center. They’re two completely separate programs.
• They could be built by different teams, in different languages, on different machines.
• If both sides just made up their own way of talking, nothing would line up. The app would ask one way, the server would expect another, and you’d get garbage back.

So we need a shared, predictable way for two programs to talk over the internet. Both sides agree on the rules ahead of time. The app knows exactly how to ask, and the server knows exactly how to answer. That agreement is what an API gives us, and REST is the most common style for building one.

🔌 What is an API?

Let’s define the word first. API stands for Application Programming Interface. That sounds heavy, so let’s break it down:

• An API is just an agreed way for two pieces of software to talk to each other. Nothing more.
• Think of it as a contract. One side promises, “if you ask me like this, I’ll answer like that.” The other side counts on that promise.
• You don’t need to know how the other side works inside. You just need to know what to ask and what you’ll get back.

A real-world way to picture it. Say you walk into a restaurant:

• You don’t go into the kitchen and cook. You talk to the waiter.
• You ask the waiter from the menu, the waiter brings your food. The menu is the agreed list of what you can order.
• The API is like that menu plus the waiter. It’s the fixed set of things you’re allowed to ask for, and the way you ask for them.

So whenever one program needs something from another, an API is the doorway. REST is simply one popular style of building that doorway for the web.

🌐 What is REST?

REST is a style for building web APIs. Let’s unpack it:

• REST stands for Representational State Transfer. The name is a mouthful, but the idea is simple.
• It’s a set of rules for how programs talk over HTTP, the same protocol your browser uses to load web pages. (HTTP is just the agreed format for asking a web server for things and getting answers back.)
• The big idea in REST is that everything is treated as a resource.

So what’s a resource? Let’s define the two words you’ll hear over and over:

• A resource is just a thing your API knows about. A user, a photo, an order, a product. Each one is a resource.
• An endpoint is the URL where you reach a resource. For example, /users/1 is the endpoint for the user whose ID is 1.

Here’s the whole flow at a glance. The client asks for a resource at an endpoint, and the server sends it back.

The word client just means whoever is asking, like your app or your browser. The server is whoever holds the data and answers. Keep that picture in your head, because everything else builds on it.

🔧 HTTP Methods = Actions

Okay, so you reach a resource at an endpoint. But what do you want to do with it? Read it? Delete it? That’s where HTTP methods come in:

• An HTTP method is a word that says what action you want to take on a resource.
• The endpoint says which thing, and the method says what to do with it.
• Same endpoint, different method, different action. GET /users/1 reads a user, DELETE /users/1 removes that same user.

These actions line up neatly with something called CRUD. CRUD is just shorthand for the four basic things you ever do with data: Create, Read, Update, and Delete. Almost every app does these four things all day long. Here’s how the methods map to them.

A quick note on PUT versus PATCH, since people mix them up. PUT replaces the whole thing, like handing over a fresh copy. PATCH just tweaks a part of it, like changing only the email and leaving the rest alone.

📦 Requests and Responses

Every REST call is two halves: you send a request, the server sends a response. Let’s look at a real one. Say your app wants to read the user with ID 1.

The request is just a small note. It says the method and the endpoint.

GET /users/1
Host: api.example.com

Let’s read it:

• GET is the method, so we’re reading, not changing anything.
• /users/1 is the endpoint, the user whose ID is 1.
• Host says which server to ask.

The server looks up that user and sends back a response. The data usually comes as JSON. JSON is just a simple text format for data, made of names and values, and both humans and machines can read it easily.

{
  "id": 1,
  "name": "Alex",
  "email": "alex@example.com"
}

Along with that data, the response carries a status code, a short number that tells you how things went. You’ve probably seen 404 before, right? Here are the ones worth knowing.

Now creating something looks a little different. You send a POST with a body, the data you want to add.

POST /users
Content-Type: application/json

{
  "name": "Alex",
  "email": "alex@example.com"
}

The server creates that user, gives it an ID, and replies with 201 Created and the new record. So the request carries what you want done, and the response carries the result plus a status code that tells you how it went.

📐 What Makes an API RESTful?

People throw around the word RESTful a lot. An API is called RESTful when it actually follows the REST style properly. So what does that take?

• Clear resource URLs. The endpoints are named after things, like /users and /users/1/orders, not after actions. The method already says the action, so the URL just names the resource.
• Standard methods. It uses GET, POST, PUT, PATCH, and DELETE the way they’re meant to be used. GET only reads, DELETE only removes, and so on.
• Meaningful status codes. It answers with the right code every time, like 200 for success and 404 when something isn’t there, so the client always knows what happened.
• JSON data. It usually sends and receives data as JSON, since nearly every language can read it.
• It’s stateless. This is the big one, so let’s define it.

What does stateless mean? It means the server doesn’t remember anything about you between requests:

• Each request has to carry everything the server needs to handle it. The server doesn’t keep your previous request in memory.
• It’s like ordering at a counter where the staff change every time. You can’t say “the usual.” You have to say your full order each time.
• This sounds like extra work, but it’s a huge win. Any server can handle any request, so you can add more servers easily when traffic grows.

⚡ Why REST is Popular

REST took over the web for some very practical reasons:

• It’s simple. Resources plus a handful of methods. That’s a small set of ideas you can learn in an afternoon.
• It rides on plain HTTP. No special tooling needed. The same protocol that loads web pages carries your API calls, and HTTP is everywhere already.
• It’s language-agnostic. A Python server and a Swift app talk just fine, because they only agree on the request format and JSON. Neither cares what the other is written in.
• It’s cacheable. Since GET requests just read and don’t change anything, their answers can be saved and reused, which makes repeat reads fast. (Saving an answer to reuse later is called caching.)

Put together, REST is easy to learn, easy to debug, and works between almost any two systems. That’s why it became the default way apps talk to servers.

⚠️ Common Mistakes and Misconceptions

A few things trip people up early. Let’s clear them out:

• “Any HTTP endpoint is a REST API.” Not really. Sending data over HTTP is just step one. To be RESTful it needs resource-based URLs, proper methods, status codes, and statelessness. A random endpoint that does everything through one URL isn’t REST.
• “It’s fine to use GET to change data.” No, this is a real trap. GET is meant to only read. If a GET deletes or updates something, caches and crawlers can trigger it by accident and wreck your data. Use POST, PUT, or DELETE for changes.
• “Status codes don’t really matter.” They matter a lot. If your server returns 200 OK even when something failed, the client has no idea anything went wrong. Send the right code so the other side can react correctly.
• “REST means the URL should describe the action.” The opposite, actually. The method is the action. So it’s DELETE /users/1, not GET /deleteUser/1. Keep verbs out of the URL.

🛠️ Design Challenge

Try this on your own to lock it in.

Imagine you’re building the API for a simple to-do list app. A to-do item is your resource. Design the endpoints for all four CRUD actions. For example:

• GET /todos to list all items, and GET /todos/1 to read one.
• POST /todos to create a new item, with the text in the request body.
• PUT /todos/1 to update item 1, and DELETE /todos/1 to remove it.

Now think about the responses. What status code should each one return? What would the JSON for a single to-do look like? Sketch it out. This is exactly the kind of thing you’d design in a real interview.

🧩 What You’ve Learned

You can now explain how apps and servers talk over the web. Here’s what you’ve picked up.

• ✅ An API is a contract, an agreed way for two pieces of software to talk.
• ✅ REST is a style for web APIs that treats everything as a resource you reach at an endpoint over HTTP.
• ✅ HTTP methods map to CRUD: GET reads, POST creates, PUT and PATCH update, DELETE removes.
• ✅ A request carries the method, endpoint, and sometimes a body. A response carries JSON data and a status code like 200 or 404.
• ✅ A RESTful API uses clear resource URLs, standard methods, meaningful status codes, JSON, and is stateless.
• ✅ REST is popular because it’s simple, rides on plain HTTP, works across languages, and is cacheable.

🚀 What’s Next?

You’ve got the foundation now. Next, see how other approaches compare and how the connection underneath stays secure.

• GraphQL Basics shows a different way to ask for data, where the client picks exactly the fields it wants.
• HTTP vs HTTPS breaks down requests, responses, and how encryption keeps your API calls safe.

Once you’ve got these, you’ll have a solid grip on how modern apps and servers talk to each other.