Construí API REST por 3 meses sem entender o que estava fazendo
Aprendi REST na raça, construindo integração de CRM sem saber o nome do que estava fazendo. Aqui está o que eu queria ter lido antes de começar.
Minha primeira API foi uma mentira.
Não intencional. Mas era. Eu fazia chamadas HTTP, recebia JSON de volta, e achava que entendia o que estava acontecendo. Não entendia.
Entendia a superfície. Entendia que GET pega coisa, POST manda coisa, e que quando o status era 200 tava tudo bem. Só isso.
Levei uns 3 meses para entender de verdade o que é REST. E entendi da pior forma — quebrando coisas em produção.
O que a teoria não deixa claro
REST não é protocolo, não é biblioteca, não é formato de dados. É estilo arquitetural — um conjunto de restrições.
Duas importam na prática:
Stateless — cada requisição carrega tudo que o servidor precisa. Sem sessão no servidor. Parece óbvio até você descobrir que sua API tem sessão no servidor, e agora tem problema de escalabilidade que não resolve sem refatorar tudo.
Uniform interface — recursos com convenções consistentes. /usuarios/123, GET retorna, PUT atualiza, DELETE deleta. Vi API onde GET /usuarios/deletar?id=123 deletava usuário. Isso não é REST. É caos com rota HTTP.
O erro que eu cometi no começo
Eu misturava recurso com ação.
Em vez de:
DELETE /pedidos/456
Eu fazia:
POST /cancelarPedido
{ "pedidoId": 456 }
Funcionava. Mas era errado. Porque quando alguém novo chegava no projeto, precisava ler a documentação de cada endpoint para entender o que fazia. Com REST correto, você lê a URL e o método HTTP — já sabe.
Convenção é documentação. Isso aprendi tarde.
O que HTTP realmente faz
Antes de entender REST, precisei entender HTTP de verdade.
HTTP é texto. Sério. Uma requisição HTTP é literalmente texto formatado viajando pela rede:
GET /usuarios/123 HTTP/1.1
Host: api.exemplo.com
Authorization: Bearer eyJ...
Accept: application/json
E a resposta é texto de volta:
HTTP/1.1 200 OK
Content-Type: application/json
{ "id": 123, "nome": "Adornete" }
Quando eu aprendi isso — que era só texto — desmistificou tudo. O erro 400 é texto. O token JWT é texto codificado em base64. O JSON é texto. Tudo viaja como texto, o formato é o que dá significado.
Isso ajudou muito quando comecei a debugar problemas de integração. Se não sabe o que está acontecendo, captura o tráfego HTTP cru. O problema sempre aparece lá.
Status code não é detalhe
200 = deu certo. 201 = criou (diferente de 200 — retorna o recurso novo e um Location header). 400 = cliente mandou coisa errada. 401 = não autenticado. 403 = autenticado mas sem permissão. 404 = não existe. 500 = erro no servidor.
O erro mais comum que vi: retornar 200 com { "success": false, "error": "não encontrado" }. Quebra todo cliente que usa status code para decidir o que fazer. Não faz isso.
Não lê RFC. Ainda não. Constrói uma API pequena — um CRUD simples de qualquer coisa — e usa o curl para fazer todas as chamadas manualmente.
curl -X POST http://localhost:3000/tarefas \
-H "Content-Type: application/json" \
-d '{"titulo": "estudar REST"}'
Observa os status codes. Observa os headers. Quebra de propósito — manda body inválido, tenta deletar recurso inexistente, manda requisição sem autenticação.
O que vai aprender bugando de propósito é mais do que qualquer tutorial vai te ensinar.
Essa semana: pega uma API que você usa no projeto e inspeciona as requisições no DevTools ou no Insomnia. Olha os headers, os status codes, o formato dos erros. Vai encontrar pelo menos uma coisa que não esperava.