REST é o estilo de arquitetura mais comum para construir APIs web hoje. Mas "ter endpoints HTTP" não torna uma API RESTful — REST é um conjunto de princípios sobre como modelar e expor recursos. Entender esses princípios é o que separa uma API previsível e fácil de consumir de uma bagunça.
A API como contrato
Uma API é um contrato entre quem fornece e quem consome. Ela define quais operações existem, o que cada uma espera receber e o que devolve. Se o contrato é claro e estável, times diferentes (ou empresas diferentes) conseguem trabalhar sem combinar nada além da documentação. Esse contrato roda sobre HTTP — vale revisar como a web funciona antes de seguir.
Recursos são substantivos
O princípio central de REST é pensar em recursos: coisas do seu domínio, expressas como substantivos no plural. /produtos, /usuarios, /pedidos. O que você faz com o recurso é expresso pelo verbo HTTP, não pela URL. Por isso /criarProduto não é RESTful — o "criar" deveria ser um POST /produtos.
Verbos HTTP e a tabela de endpoints
| Verbo | Endpoint | Ação |
|---|---|---|
| GET | /produtos | Lista todos os produtos |
| GET | /produtos/42 | Busca o produto 42 |
| POST | /produtos | Cria um novo produto |
| PUT | /produtos/42 | Substitui o produto 42 inteiro |
| PATCH | /produtos/42 | Atualiza parte do produto 42 |
| DELETE | /produtos/42 | Remove o produto 42 |
Statelessness e representações
REST é stateless: cada requisição carrega tudo que o servidor precisa para processá-la. O servidor não guarda "onde você estava" entre chamadas. Isso é o que permite escalar horizontalmente (qualquer servidor atende qualquer requisição). O recurso em si é abstrato; o que trafega é uma representação dele, quase sempre em JSON:
GET /produtos/42
200 OK
{
"id": 42,
"nome": "Teclado mecânico",
"preco": 350.00,
"emEstoque": true
}Status codes corretos
Usar o status code certo faz parte do contrato. Em entrevista é comum pedirem para explicar as famílias: 2xx sucesso (200 OK, 201 Created), 4xx erro do cliente (400 inválido, 401 não autenticado, 403 sem permissão, 404 não encontrado), 5xx erro do servidor. Retornar 200 OK com um corpo "deu erro" dentro é um clássico de API mal feita.
Métodos seguros e idempotentes
Dois conceitos importantes: um método é seguro se não altera dados (GET). É idempotente se repeti-lo produz o mesmo efeito de fazê-lo uma vez (GET, PUT, DELETE). POST não é idempotente — dois POSTs criam dois recursos. Essa noção volta a aparecer quando falamos de resiliência e retries.
O que torna uma API RESTful não é a tecnologia, e sim a disciplina: recursos como substantivos, verbos HTTP fazendo o trabalho, statelessness e status codes honestos.
O que torna uma API "não-RESTful"
Sinais de alerta: verbos na URL (/getProduto), tudo via POST, status sempre 200, ou guardar estado de sessão no servidor entre chamadas. No dia a dia isso aparece quando uma API "funciona" mas é imprevisível — cada endpoint tem sua própria lógica e você precisa ler o código para entender.
Conclusão
REST é menos sobre regras rígidas e mais sobre previsibilidade. Modele recursos, use os verbos HTTP corretamente, mantenha o servidor stateless e seja honesto nos status codes. Uma API que segue isso é fácil de consumir, documentar e escalar — e demonstra que você entende o contrato por trás da web.
REST is the most common architectural style for building web APIs today. But "having HTTP endpoints" doesn't make an API RESTful — REST is a set of principles for how to model and expose resources. Understanding those principles is what separates a predictable, easy-to-consume API from a mess.
The API as a contract
An API is a contract between whoever provides it and whoever consumes it. It defines which operations exist, what each one expects to receive and what it returns. If the contract is clear and stable, different teams (or different companies) can work together without agreeing on anything beyond the documentation. That contract runs on top of HTTP — it's worth reviewing how the web works before moving on.
Resources are nouns
The core principle of REST is to think in terms of resources: things from your domain, expressed as plural nouns. /products, /users, /orders. What you do with the resource is expressed by the HTTP verb, not by the URL. That's why /createProduct is not RESTful — the "create" should be a POST /products.
HTTP verbs and the endpoint table
| Verb | Endpoint | Action |
|---|---|---|
| GET | /products | Lists all products |
| GET | /products/42 | Fetches product 42 |
| POST | /products | Creates a new product |
| PUT | /products/42 | Replaces the whole of product 42 |
| PATCH | /products/42 | Updates part of product 42 |
| DELETE | /products/42 | Removes product 42 |
Statelessness and representations
REST is stateless: each request carries everything the server needs to process it. The server doesn't keep track of "where you were" between calls. That's what allows horizontal scaling (any server can handle any request). The resource itself is abstract; what travels over the wire is a representation of it, almost always in JSON:
GET /products/42
200 OK
{
"id": 42,
"name": "Mechanical keyboard",
"price": 350.00,
"inStock": true
}Correct status codes
Using the right status code is part of the contract. In interviews you're often asked to explain the families: 2xx success (200 OK, 201 Created), 4xx client error (400 invalid, 401 unauthenticated, 403 forbidden, 404 not found), 5xx server error. Returning 200 OK with an "error happened" message inside the body is a classic sign of a poorly built API.
Safe and idempotent methods
Two important concepts: a method is safe if it doesn't change data (GET). It is idempotent if repeating it has the same effect as doing it once (GET, PUT, DELETE). POST is not idempotent — two POSTs create two resources. This notion comes back when we talk about resilience and retries.
What makes an API RESTful isn't the technology, but the discipline: resources as nouns, HTTP verbs doing the work, statelessness and honest status codes.
What makes an API "not RESTful"
Warning signs: verbs in the URL (/getProduct), everything via POST, status always 200, or keeping session state on the server between calls. Day to day, this shows up when an API "works" but is unpredictable — each endpoint has its own logic and you have to read the code to understand it.
Conclusion
REST is less about rigid rules and more about predictability. Model resources, use HTTP verbs correctly, keep the server stateless and be honest with your status codes. An API that follows this is easy to consume, document and scale — and shows that you understand the contract behind the web.