You’ve probably used an API today without even noticing. You opened your banking app, checked the weather forecast, scrolled through your feed — all of that involves applications communicating with servers through an API. And most of the time, that conversation follows a style called REST. Let’s open the black box.
An API is just a waiter
Forget the acronym (Application Programming Interface) for a second. Think of a restaurant. You don’t go into the kitchen to fry your own egg — you tell the waiter what you want, they take the order, and come back with your meal. The API is the waiter: an intermediary with a fixed menu of things you can request.
Your app (the client) asks for something. The server prepares it and sends it back. You never access the database directly and never see the kitchen. You only know the menu — the endpoints you can call and what each one does. This separation keeps everything maintainable: the backend team can renovate the entire kitchen and, as long as the menu stays the same, your app won’t even notice.
HTTP: the language of the conversation
All this communication happens over HTTP, the same protocol used by your browser. Each request includes a method, which acts as the action’s verb:
- GET — retrieve data. “Show me the users.” It changes nothing.
- POST — create something. “Register this new user.”
- PUT — update something. “Replace this user’s data.”
- DELETE — remove something. “Delete this user.”
The key idea is that the method makes the intent explicit. GET /usuarios and DELETE /usuarios/42 refer to the same general resource, but do opposite things — and any developer reading them understands that immediately, without needing documentation. In addition to the method and URL, the request includes headers (extra information, such as who you are and which format you accept) and, for POST and PUT, a body containing the data you’re sending.
Status codes: the server answering directly
For each request, the server returns a three-digit number indicating what happened. You don’t need to memorize them all; just understand the usual ranges:
- 2xx — it worked.
200 OK(here you go),201 Created(I created what you asked for). - 4xx — the error was on your side.
400 Bad Request(you sent something malformed),401 Unauthorized(where’s your login?),403 Forbidden(you’re logged in, but don’t have permission),404 Not Found(that doesn’t exist). - 5xx — the error was on the server’s side.
500 Internal Server Error(the kitchen caught fire; it wasn’t your fault).
Just by reading the code, you already know where to look. Got a 401? Check the token. Got a 500? Don’t worry, the problem is on the other side — with the backend team.
Resources and JSON: the menu and the meal
In REST, everything revolves around resources — the nouns in your system: users, orders, and products. Each resource has a URL, and the URL represents a logical path: /usuarios is the entire list, /usuarios/42 is the user with ID 42, and /usuarios/42/pedidos are that user’s orders. Notice that these are nouns, never verbs — the HTTP method takes care of the verb.
The format in which this data travels is almost always JSON. It’s plain text, readable by both humans and machines:
{ "id": 42, "nome": "Ana", "ativo": true, "tags": ["admin", "beta"] }
Keys and values, lists, numbers, and booleans. It’s essentially an object from your code serialized as text so it can travel across the internet and be reconstructed on the other side.
Stateless and tokens: the server has amnesia
Here’s the tricky part that confuses almost everyone at first: a REST API is stateless. In other words, the server doesn’t remember you from one request to the next. Every request arrives from scratch, as if it were the first one. There’s no “but I just logged in on the previous request” — as far as the server is concerned, the previous request never existed.
So how does the server know who you are? You tell it again every time. After logging in, you receive a token — a long string that works like an ID badge. Then, on every subsequent request, you attach that token in a header:
Authorization: Bearer eyJhbGciOiJIUzI1Ni...
The server reads the badge, checks whether it’s valid, and grants access (or rejects the request with a 401). This is what makes the API scalable: any server in the fleet can handle your request because everything it needs to know about you comes with the request itself.
Getting hands-on: curl and Postman
Enough theory. The best way to understand an API is to poke at it. Two tools can take you a long way.
curl already comes with your terminal and gets straight to the point:
bash curl -X GET https://api.exemplo.com/usuarios/42 \ -H "Authorization: Bearer SEU_TOKEN"
A POST request sending JSON isn’t much more difficult:
bash curl -X POST https://api.exemplo.com/usuarios \ -H "Authorization: Bearer SEU_TOKEN" \ -H "Content-Type: application/json" \ -d '{"nome": "Ana", "ativo": true}'
-X selects the method, each -H is a header, and -d is the body. Notice that everything is right there: method, URL, token in the header, and JSON in the body. It’s the entire conversation in one command.
Postman is the graphical-interface version: you enter the URL, choose the method from a dropdown, configure headers and the body in separate fields, click Send, and see the formatted response with the status code right in front of you. For exploring a new API or debugging, it’s hard to beat.
That’s it. Now, when you read “send a GET request to this endpoint and pass the token in the header,” it won’t sound like Greek anymore. It’s just the waiter, the order, and the ID badge. The rest is practice: pick any public API, open Postman, and start poking around.
