How REST APIs Work: A Step-by-Step Guide for Beginners

by Souy Soeng /October 13, 2026

Diagram of a client sending a REST API request to a server, with GET, POST, PUT and DELETE method labels

A REST API is a set of rules that lets programs request and exchange data over the web, and learning how REST APIs work comes down to one simple conversation: a client asks, a server answers. When your phone loads the weather or a new message, it is sending a request to a server and reading the reply.

This guide walks through that conversation in order. You will find an endpoint, pick the right HTTP method, send real requests from your own computer with curl, and learn to read the status code and JSON data that come back. You don't need any coding experience. If you know what a web address is, you're ready.

In short

A client sends a request to an endpoint, which is a URL naming one resource.
The HTTP method (GET, POST, PUT or DELETE) says what action to take.
The server replies with a three-digit status code, usually followed by JSON data.
Always check the status code before trusting the data.
Keep secret API keys on a server, never in browser or app code.

Picture the client, the server and the API

Before sending anything, it helps to know who is talking. Your weather app is the client. It sends a request to the REST API, which defines exactly how that request must be written. Behind the API, a server does the real work, pulling forecasts from a database, and then the answer travels back to the app.

Keep one sentence in mind: one side asks, the other side answers, and the API is the agreement between them. Without shared rules, every app would invent its own way to talk. REST gives everyone the same simple, predictable pattern, so a weather app and a server built by complete strangers can still understand each other.

To follow along, you need a computer with internet access, a terminal with curl (built in on Mac, Linux and recent versions of Windows) and a web browser. If you prefer clicking to typing, a visual tool such as Postman does the same job, and the ideas are identical.

Client: the app or tool that sends the request
API: the rules for how to ask
Server: the program that processes the request and replies
Database: where the server reads or saves the data

Find the endpoint for the data you need

Every request goes to a URL called an endpoint, and each endpoint points at one resource, such as users, messages or forecasts. Think of it as a street address for one kind of data on the server. Get the address right, and the rest becomes much easier.

In the examples below, the first endpoint returns a list of users. Adding 42 to the path narrows it to a single user. The last one adds a question mark and a query, asking for the weather in Paris specifically.

The first part, api.example.com, is the base URL. It stays the same for every request to this API, and you'll usually find it near the top of the API's documentation. The part after the slash is the resource path. Good REST APIs name resources with plain nouns like /users or /orders rather than verbs like /getUsers, because the action comes from the HTTP method instead.

Find the base URL in the API's documentation
Use the resource path for the data you want, such as /users
Add an id to target one item, such as /users/42
Add a query after ? to filter results

# base URL + resource path
https://api.example.com/users
https://api.example.com/users/42
https://api.example.com/weather?city=Paris

Choose the right HTTP method

Once you have the address, you need to say what you want done there. That's the job of the HTTP method, a single word at the start of every request. The same endpoint can mean four different things depending on which method you use. A simple way to remember it: the URL says what, and the method says do what.

GET reads data and never changes anything, such as loading user 42's profile. POST creates something new, such as sending a message. PUT updates an existing item, such as editing your display name. DELETE removes an item, such as deleting an old post.

There is one important difference to watch. Repeating a GET, PUT or DELETE request gives the same result each time. Repeating a POST does not, because each one can create a new item. That's why clicking submit twice on a payment form could create two orders, and why many apps disable the button after the first click.

GET: read data, change nothing
POST: create a new item
PUT: update an existing item
DELETE: remove an item

Send your first GET request with curl

Now it's time to send something real. Open your terminal. curl is a small tool that sends web requests from the command line, with no browser needed. The example below uses a free test API, so you can try it safely.

First, save the base address in a variable, then run curl followed by /users/1. You should see a block of text describing a user named Leanne. Add the -i flag, and curl also shows the status line and the response headers above the data.

Notice that you never typed the word GET. curl assumes GET unless you name another method, which makes sense, because reading data is the most common thing you'll do with any API. As a quick check, paste the same address into a browser tab. The address bar always sends GET requests, so you'll see the same data, just formatted a little differently.

The response describes a user named Leanne
Adding -i shows the status line and headers
The same URL in a browser returns the same data

# read one user (GET is the default)
API=https://jsonplaceholder.typicode.com
curl $API/users/1
# -i also shows status and headers
curl -i $API/users/1

Send data with POST, PUT and DELETE

Reading is only half the story. When you post a photo or edit your profile, an app sends data along with its request. In curl, two flags make this possible: -X chooses the method, and -d sends the data, usually written as JSON.

Run the POST command below, and the server replies with your new post plus an id it assigned. The -H line sets the Content-Type header, which tells the server the body is JSON. PUT works the same way, with a body holding the updated fields, and the last line deletes post 1.

If you leave out the Content-Type header, many servers won't understand your body. They may reject it or quietly ignore the data, which is one of the most common reasons a POST seems to do nothing. You can experiment freely here: this practice API pretends to save your changes but doesn't actually keep them.

Use -X to choose POST, PUT or DELETE
Use -d to send the JSON body
Set Content-Type: application/json when sending JSON
Expect the POST response to include a new id

# create a new post
curl -X POST $API/posts \
  -H "Content-Type: application/json" \
  -d '{"title":"Hello"}'
# remove post 1
curl -X DELETE $API/posts/1

Trace the request and read the status code first

After you press Enter, the server passes your request through several layers, much like an elevator riding down and back up. A router matches the URL and method to the right code. An auth check confirms you're allowed in. The app logic does the work, and the database reads or saves the data before the answer climbs back. If any layer says no, the server stops and answers immediately, so a bad key never reaches the database.

REST servers are also stateless: they don't remember your previous request. Every request has to carry everything the server needs, such as your key and the exact resource. That's why the same request behaves the same way each time.

When the reply arrives, look at the three-digit status code before the data. The first digit tells you most of the story: 2xx means success, 4xx means the request was wrong, and 5xx means the server had a problem. For example, GET /users/999 matches the users route, so the address is valid, but the database finds no user 999, so the server answers 404 Not Found.

200 OK: the request succeeded
201 Created: something new was made
401 Unauthorized: your key is missing or wrong
404 Not Found: the resource doesn't exist
500 Server Error: the server broke, not you

Read the JSON response

Once the status code says success, you can read the data itself. Most REST APIs reply in JSON, short for JavaScript Object Notation. Despite the name, almost any programming language can read it, and it's simple enough for people to scan by eye.

The example below is a trimmed version of the user you fetched earlier. Each line pairs a name in quotes with a value. The id is a number, the name and email are text, and the address holds its own small object with a city inside. To read JSON, find the key you care about, then read what comes after the colon. In code, you'd write something like user.name to get Leanne Graham directly.

Long responses sometimes arrive as one squashed line. Piping curl's output into a tool called jq formats and colours it in the terminal, and browsers such as Firefox display JSON neatly on their own.

Find the key, then read the value after the colon
Curly braces wrap an object, including nested ones
Use jq to make long responses readable

{
  "id": 1,
  "name": "Leanne Graham",
  "email": "Sincere@april.biz",
  "address": { "city": "Gwenborough" }
}

Confirm it works and fix common mistakes

To check the whole round trip, send GET to /users/1 with curl -i and look for three things: the right code, the right format and the right content. You should see 200 OK at the top, followed by JSON data, with a name field reading Leanne Graham. Then break it on purpose by changing the id to 999. If you now get 404 instead of 200, your mental model is working.

When a request fails or behaves strangely, check three classic mistakes first. Using the wrong method, such as sending GET where the endpoint expects POST, often returns 405 Method Not Allowed or changes nothing; match the method to the documentation. Ignoring the status code can make your code treat a 401 error message as user data and crash later in a confusing place, so check the code first. Finally, never expose a secret API key in website code or a public GitHub repository, because anyone can copy it and use it in your name.

A 2xx status code at the top of the response
JSON data in the body
The fields you expected, such as the correct name
A 404 when you request an id that doesn't exist

Keep your API keys safe on a server

Many real services require a secret key, and the safest pattern is to never let the browser or phone see it at all. The user's browser asks your own server for the weather, with no key attached. Your server reads the secret from an environment variable, calls the weather API with the key, and passes back only the forecast.

This is the setup professional apps use, and it's what lets small teams build big apps. A website can call a weather service, a social feed, a payment service and a maps service without building any of them itself. Whichever API you use, start with its documentation: it lists every endpoint, the method each one expects, what responses look like, and any limits on how often you can call it.

Store secret keys in environment variables on a server
Let your server call the API and return only the result
Check the documentation for endpoints, methods and usage limits

Key takeaways

A client sends a request to an endpoint, a URL that names one resource.
The method says what to do: GET reads, POST creates, PUT updates, DELETE removes.
The server processes the request and replies with a status code.
Read the status code before the data; 2xx means success.
JSON carries the data as keys and values.
Keep secret keys on a server, never in front-end code.

Frequently asked questions

What is a REST API in simple terms?

A REST API is a set of rules that lets programs request and exchange data over the web. One program, the client, sends a request to a URL, and a server sends back an answer, usually as JSON.

What is the difference between POST and PUT?

POST creates a new item, such as a new message, while PUT updates an item that already exists, such as your display name. Repeating a PUT gives the same result, but repeating a POST can create a second item.

Do I need to know how to code to try a REST API?

No. You can send requests with curl in a terminal or with a visual tool such as Postman. For simple GET requests, you can even paste the URL into your browser's address bar.

Why does curl use GET when I don't specify a method?

curl defaults to GET because reading data is the most common thing people do with an API. To use another method, add the -X flag, for example -X POST.

What does a 404 or 401 status code mean?

A 404 means the resource you asked for doesn't exist, such as a user id that isn't in the database. A 401 means your API key is missing or wrong, so the server refused the request.

Why shouldn't I put my API key in front-end code?

Anything in website code or a public repository can be copied, and someone could use your key in your name. Store the key in an environment variable on your own server and let the server make the API call.

Watch the full video on YouTube →

Tag

Ad